Skip to content

"Vibe-Trading: Your Personal Trading Agent"

29.3 KB
Raw Blame
"""Tests for PersistentMemory: file-based cross-session memory."""

from __future__ import annotations

from pathlib import Path

import pytest

from src.memory.persistent import (
    MAX_ENTRY_CHARS,
    MemoryEntry,
    PersistentMemory,
    _coerce_str,
    _sanitize_body,
    _tokenize,
    _truncate_body,
)


class TestCoerceStr:
    def test_passthrough_string(self) -> None:
        assert _coerce_str("hello") == "hello"

    def test_none_uses_default(self) -> None:
        assert _coerce_str(None, default="fallback") == "fallback"

    def test_list_joined_with_comma(self) -> None:
        # `description: [red]inject[/red]` would parse to a single-element list
        # because the frontmatter parser treats ``[...]`` as a list literal.
        assert _coerce_str(["red]inject[/red"]) == "red]inject[/red"
        assert _coerce_str(["a", "b"]) == "a, b"

    def test_bool_lowercased(self) -> None:
        assert _coerce_str(True) == "true"
        assert _coerce_str(False) == "false"


class TestScanEntriesCoercesFrontmatter:
    def test_bracketed_description_renders_as_string(self, tmp_path) -> None:
        # Regression: a description like ``[red]x[/red]`` parsed as a list used
        # to leak through MemoryEntry.description and crash any downstream
        # consumer that called string ops on it (e.g. rich.markup.escape).
        entry_path = tmp_path / "user_bracket-desc.md"
        entry_path.write_text(
            "---\nname: bracket-desc\ndescription: [red]inject[/red]\ntype: user\n---\n\nbody\n",
            encoding="utf-8",
        )
        pm = PersistentMemory(memory_dir=tmp_path)
        entries = pm.list_entries()
        assert len(entries) == 1
        assert isinstance(entries[0].description, str)


# ---------------------------------------------------------------------------
# _tokenize
# ---------------------------------------------------------------------------


class TestTokenize:
    def test_ascii_words(self) -> None:
        tokens = _tokenize("hello world testing")
        assert "hello" in tokens
        assert "world" in tokens
        assert "testing" in tokens

    def test_single_char_words_excluded(self) -> None:
        tokens = _tokenize("I a")
        # Single ASCII chars carry no discriminating value, should be excluded
        assert len(tokens) == 0

    def test_two_char_words_included(self) -> None:
        # Regression: the fallback token-scan used a 3-char minimum while
        # search_index.py's FTS5 sanitizer used 2 chars, so short tokens like
        # ticker symbols ("GE") or country codes ("US") were retrievable via
        # FTS but silently invisible whenever VT_MEMORY_FTS_INDEX was off.
        tokens = _tokenize("GE US ok no")
        assert tokens == {"ge", "us", "ok", "no"}

    def test_cjk_characters(self) -> None:
        tokens = _tokenize("比特币价格分析")
        assert "比" in tokens
        assert "币" in tokens
        assert "价" in tokens

    def test_mixed(self) -> None:
        tokens = _tokenize("AAPL 苹果 stock analysis")
        assert "aapl" in tokens
        assert "苹" in tokens
        assert "stock" in tokens
        assert "analysis" in tokens

    def test_empty(self) -> None:
        assert _tokenize("") == set()

    def test_underscores_split(self) -> None:
        # snake_case titles must match natural-language queries.
        # Regression: previously _tokenize treated underscores as word chars,
        # so "mcp_wiring_test" became a single token and queries like
        # "mcp wiring" never matched.
        tokens = _tokenize("mcp_wiring_test")
        assert tokens == {"mcp", "wiring", "test"}

    def test_thai_characters(self) -> None:
        # Thai script (฀-๿) was not tokenized — recall on Thai
        # queries always returned the empty set. Char-level like CJK.
        tokens = _tokenize("นโยบายการเทรด")
        assert "น" in tokens
        assert "เ" in tokens
        assert "ท" in tokens

    def test_arabic_characters(self) -> None:
        tokens = _tokenize("التداول")
        assert "ا" in tokens
        assert "ل" in tokens

    def test_hebrew_characters(self) -> None:
        tokens = _tokenize("מסחר")
        assert "מ" in tokens
        assert "ס" in tokens

    def test_cyrillic_characters(self) -> None:
        tokens = _tokenize("торговля")
        assert "т" in tokens
        assert "о" in tokens


# ---------------------------------------------------------------------------
# PersistentMemory.add
# ---------------------------------------------------------------------------


class TestAdd:
    def test_creates_file_and_index(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        path = pm.add("test-mem", "Some content", "project", description="Test desc")
        assert path.exists()
        assert "test-mem" in path.read_text(encoding="utf-8")
        index = (tmp_path / "MEMORY.md").read_text(encoding="utf-8")
        assert "test-mem" in index

    def test_slug_sanitization(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        path = pm.add("My Fancy Skill!", "body", "user")
        assert "my_fancy_skill_" in path.name

    def test_frontmatter_structure(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        path = pm.add("meta-test", "body here", "feedback", description="one line")
        text = path.read_text(encoding="utf-8")
        assert text.startswith("---\n")
        assert "name: meta-test" in text
        assert "type: feedback" in text
        assert "description: one line" in text
        assert "body here" in text

    def test_multiple_adds(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        pm.add("mem-a", "aaa", "project")
        pm.add("mem-b", "bbb", "user")
        pm.add("mem-c", "ccc", "reference")
        md_files = list(tmp_path.glob("*.md"))
        # 3 entries + MEMORY.md = 4
        assert len(md_files) == 4

    def test_overwrite_same_name(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        pm.add("overwrite", "v1", "project")
        pm.add("overwrite", "v2", "project")
        # Should overwrite the same file
        path = tmp_path / "project_overwrite.md"
        assert "v2" in path.read_text(encoding="utf-8")

    @pytest.mark.parametrize("title", ["นโยบาย", "التداول", "מסחר", "торговля"])
    def test_slug_preserves_non_latin_chars(self, tmp_path: Path, title: str) -> None:
        # Regression: non-Latin chars used to collapse to "_" in slug,
        # causing two distinct titles of equal length to collide.
        pm = PersistentMemory(memory_dir=tmp_path)
        path = pm.add(title, "body", "user")
        assert title in path.name

    def test_slug_distinguishes_two_thai_titles(self, tmp_path: Path) -> None:
        # Two different Thai titles must produce different files. Without the
        # fix both would collapse to "user________.md".
        pm = PersistentMemory(memory_dir=tmp_path)
        a = pm.add("นโยบาย", "rule a", "user")
        b = pm.add("กลยุทธ์", "rule b", "user")
        assert a != b
        assert "rule a" in a.read_text(encoding="utf-8")
        assert "rule b" in b.read_text(encoding="utf-8")

    def test_index_update_not_duplicate(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        pm.add("dup-check", "v1", "project")
        pm.add("dup-check", "v2", "project")
        index = (tmp_path / "MEMORY.md").read_text(encoding="utf-8")
        assert index.count("[dup-check]") == 1

    def test_same_title_different_types_keep_separate_index_rows(
        self, tmp_path: Path
    ) -> None:
        # Same title, different memory_type: add() writes two distinct
        # files ("reference_kb-entry.md", "user_kb-entry.md"), so the index
        # must keep two rows rather than the second add() clobbering the
        # first entry's row just because the title matches.
        pm = PersistentMemory(memory_dir=tmp_path)
        pm.add(
            "kb-entry", "raw material notes", "reference", description="reference doc"
        )
        pm.add("kb-entry", "user preference notes", "user", description="user pref")

        assert (tmp_path / "reference_kb-entry.md").exists()
        assert (tmp_path / "user_kb-entry.md").exists()

        index = (tmp_path / "MEMORY.md").read_text(encoding="utf-8")
        assert index.count("[kb-entry]") == 2
        assert "reference_kb-entry.md" in index
        assert "user_kb-entry.md" in index

    def test_remove_names_the_type_when_a_title_is_shared(self, tmp_path: Path) -> None:
        # Sibling of the index fix: remove(title) used to delete whichever
        # same-title entry it scanned first.
        pm = PersistentMemory(memory_dir=tmp_path)
        pm.add("kb-entry", "raw material notes", "reference", description="reference doc")
        pm.add("kb-entry", "user preference notes", "user", description="user pref")

        with pytest.raises(ValueError, match="reference, user"):
            pm.remove("kb-entry")
        assert (tmp_path / "reference_kb-entry.md").exists()
        assert (tmp_path / "user_kb-entry.md").exists()

        assert pm.remove("kb-entry", "user") is True
        assert not (tmp_path / "user_kb-entry.md").exists()
        assert (tmp_path / "reference_kb-entry.md").exists()
        index = (tmp_path / "MEMORY.md").read_text(encoding="utf-8")
        assert "reference_kb-entry.md" in index and "user_kb-entry.md" not in index

        assert pm.remove("kb-entry") is True  # no longer ambiguous
        assert pm.remove("kb-entry") is False

    def test_cjk_names_get_distinct_filenames(self, tmp_path: Path) -> None:
        # Regression: previously every non-ASCII char was replaced with `_`, so
        # any two CJK-only names of the same length collapsed to the same slug
        # (e.g. "上证指数" and "黄金价格" both → "____") and the second add
        # silently overwrote the first.
        pm = PersistentMemory(memory_dir=tmp_path)
        path1 = pm.add("上证指数", "A股大盘", "project", description="A股市场")
        path2 = pm.add("黄金价格", "黄金现货", "project", description="贵金属")
        assert path1 != path2
        assert path1.exists()
        assert path2.exists()
        # Both bodies preserved on disk.
        assert "A股大盘" in path1.read_text(encoding="utf-8")
        assert "黄金现货" in path2.read_text(encoding="utf-8")
        # Index lists both.
        index = (tmp_path / "MEMORY.md").read_text(encoding="utf-8")
        assert "上证指数" in index
        assert "黄金价格" in index

    def test_cjk_name_is_findable_after_add(self, tmp_path: Path) -> None:
        # The frontmatter name still carries the original CJK title, so search
        # by CJK token still hits even though the filename slug is mangled.
        pm = PersistentMemory(memory_dir=tmp_path)
        pm.add("人民币汇率", "USD/CNY 中间价", "project", description="汇率播报")
        results = pm.find_relevant("人民币")
        assert len(results) == 1
        assert results[0].title == "人民币汇率"

    def test_update_index_exact_title_match(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        pm.add("Ref", "referencing main", "project", description="See details in [Main]")
        pm.add("Main", "main content", "project", description="Main memory entry")
        index_content = (tmp_path / "MEMORY.md").read_text(encoding="utf-8")
        lines = [line for line in index_content.splitlines() if line.strip()]
        assert len(lines) == 2
        assert any(line.startswith("- [Ref](") for line in lines)
        assert any(line.startswith("- [Main](") for line in lines)

    def test_hierarchy_routed_entry_stays_scannable(
        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        # Regression: with VT_MEMORY_HIERARCHY enabled, add() used to hand the
        # bare slug to MemoryHierarchy.route_entry(), which treats its argument
        # as the leaf filename verbatim — the entry was written without the
        # .md extension and scan_all() (suffix == ".md" filter) could not see
        # it, so the memory vanished from list_entries()/find().
        monkeypatch.setenv("VT_MEMORY_HIERARCHY", "1")
        pm = PersistentMemory(memory_dir=tmp_path)
        path = pm.add("routed-mem", "body text", "project", description="routed")
        assert path.suffix == ".md"
        assert path.parent.name == "project"
        entries = pm.list_entries()
        assert len(entries) == 1
        assert entries[0].title == "routed-mem"
        assert pm.find("routed-mem") is not None

    def test_hierarchy_same_title_different_types_keep_separate_index_rows(
        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        # Sibling of test_same_title_different_types_keep_separate_index_rows,
        # but under VT_MEMORY_HIERARCHY. There, route_entry() drops the
        # memory_type prefix from the filename (it lives in the category
        # subdirectory instead), so both entries shared the same bare
        # "{slug}.md" and the second add() clobbered the first entry's
        # index row.
        monkeypatch.setenv("VT_MEMORY_HIERARCHY", "1")
        pm = PersistentMemory(memory_dir=tmp_path)
        pm.add(
            "kb-entry", "raw material notes", "reference", description="reference doc"
        )
        pm.add("kb-entry", "user preference notes", "user", description="user pref")

        assert (tmp_path / "reference" / "kb-entry.md").exists()
        assert (tmp_path / "user" / "kb-entry.md").exists()

        index = (tmp_path / "MEMORY.md").read_text(encoding="utf-8")
        assert index.count("[kb-entry]") == 2
        assert "reference/kb-entry.md" in index
        assert "user/kb-entry.md" in index

    def test_hierarchy_same_title_is_a_link_candidate_not_self(
        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        # The link graph keyed candidates by path.name too, so under
        # VT_MEMORY_HIERARCHY the OTHER entry sharing this title was dropped
        # from the corpus as "self" (discover_links excludes by that key) and
        # any target it did write was ambiguous between the two files.
        monkeypatch.setenv("VT_MEMORY_HIERARCHY", "1")
        monkeypatch.setenv("VT_MEMORY_LINKS", "true")
        pm = PersistentMemory(memory_dir=tmp_path)
        pm.add(
            "kb-entry",
            "tencent kline pagination walks backward from end",
            "reference",
            description="tencent kline pagination reference",
        )
        second = pm.add(
            "kb-entry",
            "tencent kline pagination walks backward from end",
            "user",
            description="tencent kline pagination preference",
        )
        assert second is not None

        from src.memory.semantic_links import SemanticLinker

        targets = [
            target for target, _score in SemanticLinker(tmp_path).load_relations(second)
        ]
        assert "reference/kb-entry.md" in targets

    def test_recovered_orphan_and_new_write_agree_on_the_same_path(
        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        """The write path and the orphan recovery must name entries identically.

        ``recover_extensionless_entries`` renames an orphan by appending the
        missing suffix, so it produces ``<category>/<slug>.md``. If the write
        path is ever changed to a different convention, the same logical entry
        exists twice — once under the recovered name, once under the new one —
        and both show up in ``list_entries()``. This pins the agreement rather
        than the spelling: it asks the two code paths for the same entry and
        requires one file.
        """
        from src.memory.hierarchy import MemoryHierarchy

        monkeypatch.setenv("VT_MEMORY_HIERARCHY", "1")
        category = tmp_path / "project"
        category.mkdir()
        orphan = category / "shared-slug"
        orphan.write_text(
            "---\nname: shared-slug\ndescription: d\nmetadata:\n  type: project\n---\n\nold\n",
            encoding="utf-8",
        )
        recovered = MemoryHierarchy(tmp_path).recover_extensionless_entries()
        assert len(recovered) == 1

        written = PersistentMemory(memory_dir=tmp_path).add(
            "shared-slug", "new body", "project", description="d",
        )

        assert written == recovered[0]
        assert sorted(p.name for p in category.iterdir()) == ["shared-slug.md"]


# ---------------------------------------------------------------------------
# PersistentMemory.find_relevant
# ---------------------------------------------------------------------------


class TestFindRelevant:
    def test_basic_search(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        pm.add("btc-strategy", "Bitcoin mean reversion", "project", description="BTC trading strategy")
        pm.add("aapl-analysis", "Apple earnings report", "project", description="AAPL fundamental analysis")
        results = pm.find_relevant("Bitcoin trading")
        assert len(results) >= 1
        assert results[0].title == "btc-strategy"

    def test_cjk_search(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        pm.add("a-share", "上证指数分析报告", "project", description="A股市场分析")
        results = pm.find_relevant("上证指数")
        assert len(results) >= 1

    def test_no_match(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        pm.add("something", "unrelated content", "project")
        results = pm.find_relevant("xyznonexistent999")
        assert len(results) == 0

    def test_max_results(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        for i in range(10):
            pm.add(f"stock-{i}", f"stock analysis number {i}", "project", description=f"stock {i}")
        results = pm.find_relevant("stock analysis", max_results=3)
        assert len(results) == 3

    def test_max_results_with_semantic_links(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
        monkeypatch.setenv("VT_MEMORY_LINKS", "true")
        pm = PersistentMemory(memory_dir=tmp_path)
        p1 = pm.add("stock-0", "stock analysis zero", "project", description="stock zero")
        p2 = pm.add("stock-1", "stock analysis one", "project", description="stock one")
        p3 = pm.add("stock-2", "stock analysis two", "project", description="stock two")
        assert p1 is not None and p2 is not None and p3 is not None
        from src.memory.semantic_links import SemanticLinker
        linker = SemanticLinker(tmp_path)
        linker.save_relations(p1, [(str(p3), 0.95)])
        results = pm.find_relevant("stock analysis", max_results=2)
        assert len(results) == 2

    def test_metadata_weighted_higher(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        # "bitcoin" in description (metadata) → weighted 2x
        pm.add("meta-match", "unrelated body text", "project", description="bitcoin trading strategy")
        # "bitcoin" only in body → weighted 1x
        pm.add("body-match", "bitcoin analysis deep dive", "project", description="some other topic")
        results = pm.find_relevant("bitcoin")
        assert len(results) == 2
        assert results[0].title == "meta-match"

    def test_empty_query(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        pm.add("anything", "content", "project")
        results = pm.find_relevant("")
        assert results == []


# ---------------------------------------------------------------------------
# PersistentMemory.remove
# ---------------------------------------------------------------------------


class TestRemove:
    def test_remove_existing(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        pm.add("to-remove", "gone soon", "project")
        assert pm.remove("to-remove") is True
        # File gone
        assert not list(tmp_path.glob("*to_remove*"))
        # Index rebuilt without it
        index = (tmp_path / "MEMORY.md").read_text(encoding="utf-8")
        assert "to-remove" not in index

    def test_remove_nonexistent(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        assert pm.remove("ghost") is False

    def test_remove_then_find(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        pm.add("ephemeral", "temporary data", "project", description="temp")
        pm.remove("ephemeral")
        results = pm.find_relevant("temporary")
        assert len(results) == 0

    def test_remove_by_filename_stem(self, tmp_path: Path) -> None:
        """remove() should resolve a filename stem the same way find() does,
        not just an exact title match."""
        pm = PersistentMemory(memory_dir=tmp_path)
        pm.add("Q2 Planning", "roadmap notes", "project")
        assert pm.remove("project_q2_planning") is True
        assert pm.find("Q2 Planning") is None


# ---------------------------------------------------------------------------
# PersistentMemory.snapshot
# ---------------------------------------------------------------------------


class TestSnapshot:
    def test_snapshot_loaded_at_init(self, tmp_path: Path) -> None:
        pm1 = PersistentMemory(memory_dir=tmp_path)
        pm1.add("snap-test", "content", "project", description="snapshot check")
        # New instance should load snapshot from MEMORY.md
        pm2 = PersistentMemory(memory_dir=tmp_path)
        assert "snap-test" in pm2.snapshot

    def test_snapshot_frozen(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        pm.add("after-init", "new content", "project")
        # Snapshot was frozen at init time (before add), so it should NOT contain "after-init"
        # unless the dir was empty at init (then snapshot is empty string)
        # In either case, snapshot should not update after add
        snap_before_check = pm.snapshot
        pm.add("another", "more content", "project")
        assert pm.snapshot == snap_before_check

    def test_empty_dir_snapshot(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        assert pm.snapshot == ""


class TestSanitizeBody:
    """Regression for #108 — strip C0/C1 control bytes from agent-supplied content."""

    def test_strips_ansi_escape(self) -> None:
        assert _sanitize_body("hello\x1b[31mred\x1b[0m world") == "hello[31mred[0m world"

    def test_strips_null_and_bell(self) -> None:
        assert _sanitize_body("a\x00b\x07c") == "abc"

    def test_preserves_tab_and_newline(self) -> None:
        assert _sanitize_body("line1\nline2\tindented") == "line1\nline2\tindented"

    def test_strips_c1_range(self) -> None:
        # U+0080 to U+009F are C1 controls (PAD, NEL, etc.)
        assert _sanitize_body("a\x80b\x9fc") == "abc"

    def test_empty_passthrough(self) -> None:
        assert _sanitize_body("") == ""


class TestTruncateBody:
    """Regression for #109 — enforce MAX_ENTRY_CHARS at write with visible marker."""

    def test_short_passthrough(self) -> None:
        assert _truncate_body("short") == "short"

    def test_at_limit_passthrough(self) -> None:
        text = "x" * MAX_ENTRY_CHARS
        assert _truncate_body(text) == text

    def test_over_limit_truncated_with_marker(self) -> None:
        text = "x" * (MAX_ENTRY_CHARS + 100)
        out = _truncate_body(text)
        # Total body length stays within MAX_ENTRY_CHARS so the marker survives
        # the read-side clip in _scan_entries.
        assert len(out) <= MAX_ENTRY_CHARS
        # Marker is at the tail; head still starts with content.
        assert out.startswith("x")
        assert out.endswith("chars]\n")
        assert "[truncated at" in out
        assert str(MAX_ENTRY_CHARS) in out

    def test_custom_limit(self) -> None:
        # Custom limit must be large enough to fit the marker plus some head.
        text = "abcdef" * 100  # 600 chars
        out = _truncate_body(text, limit=100)
        assert len(out) <= 100
        assert out.startswith("abc")
        assert "[truncated at 100 chars]" in out


class TestAddRejectsEmptyName:
    """Regression for #110 — reject empty / whitespace-only names."""

    def test_empty_raises(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        with pytest.raises(ValueError, match="empty or whitespace"):
            pm.add("", "body", "user")

    def test_whitespace_only_raises(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        with pytest.raises(ValueError, match="empty or whitespace"):
            pm.add("   ", "body", "user")

    def test_tab_only_raises(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        with pytest.raises(ValueError):
            pm.add("\t\n  ", "body", "user")


class TestAddHashSuffixForCollapsedSlug:
    """Regression for #110 — distinct emoji-only / punctuation-only names must
    produce distinct files via deterministic hash suffix."""

    def test_two_distinct_emoji_names_no_collision(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        p1 = pm.add("🚀", "rocket body", "reference")  # 🚀
        p2 = pm.add("🎯", "target body", "reference")  # 🎯
        assert p1 != p2
        assert "rocket body" in p1.read_text(encoding="utf-8")
        assert "target body" in p2.read_text(encoding="utf-8")

    def test_hash_is_deterministic(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        p1 = pm.add("🚀", "v1", "reference")
        p2 = pm.add("🚀", "v2", "reference")
        # Same name → same slug → overwrite (this is expected and desired
        # for the "edit memory" workflow).
        assert p1 == p2
        assert "v2" in p1.read_text(encoding="utf-8")

    def test_punctuation_only_name_gets_hash(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        path = pm.add("???", "body", "user")
        # Slug ??? -> _ after sanitization; hash appended.
        # File name must not be just "user_.md".
        assert path.name != "user_.md"
        assert path.exists()


class TestAddSanitizesAndTruncates:
    """Regression for #108 + #109 wired into `PersistentMemory.add()`."""

    def test_add_strips_control_bytes_in_body(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        path = pm.add("ctrl-test", "before\x1b[31mred\x1b[0mafter", "user")
        body_on_disk = path.read_text(encoding="utf-8")
        # ESC byte must be gone; surrounding text preserved.
        assert "\x1b" not in body_on_disk
        assert "before" in body_on_disk and "after" in body_on_disk
        assert "[31m" in body_on_disk  # the textual remainder is fine

    def test_add_truncates_long_body_with_marker(self, tmp_path: Path) -> None:
        pm = PersistentMemory(memory_dir=tmp_path)
        path = pm.add("long-content", "x" * (MAX_ENTRY_CHARS + 500), "reference")
        body_on_disk = path.read_text(encoding="utf-8").split("---\n\n", 1)[1]
        assert len(body_on_disk) <= MAX_ENTRY_CHARS + len("\n\n[truncated at  chars]\n") + 20
        assert "[truncated at" in body_on_disk


# ---------------------------------------------------------------------------
# MemoryEntry new field defaults (Tier 2)
# ---------------------------------------------------------------------------


class TestMemoryEntryNewFields:
    """Verify Tier 2 MemoryEntry fields have safe defaults."""

    def test_memory_entry_new_fields_defaults(self) -> None:
        """category='' and compression_level='raw' by default."""
        entry = MemoryEntry(
            path=Path("/tmp/test.md"),
            title="test",
            description="desc",
            memory_type="project",
            body="body content",
            modified_at=1000.0,
        )
        assert entry.category == ""
        assert entry.compression_level == "raw"

    def test_scan_entries_reads_category_from_frontmatter(self, tmp_path: Path) -> None:
        """Write .md with category in frontmatter, verify it's parsed."""
        entry_path = tmp_path / "user_cattest.md"
        entry_path.write_text(
            "---\nname: cattest\ndescription: test category\n"
            "type: user\ncategory: user\ncompression_level: daily\n---\n\nbody\n",
            encoding="utf-8",
        )
        pm = PersistentMemory(memory_dir=tmp_path)
        entries = pm.list_entries()
        assert len(entries) == 1
        assert entries[0].category == "user"
        assert entries[0].compression_level == "daily"


def test_offsetless_frontmatter_timestamp_is_read_as_utc(monkeypatch) -> None:
    """Writers stamp ``time.gmtime()`` with no offset; reading it back must not
    shift it by the host's UTC offset."""
    import time
    from datetime import datetime, timezone

    from src.memory.persistent import _parse_timestamp

    monkeypatch.setenv("TZ", "Asia/Shanghai")
    time.tzset()
    try:
        stamp = time.strftime("%Y-%m-%dT%H:%M:%S", time.gmtime(1_800_000_000))
        assert _parse_timestamp(stamp, 0.0) == 1_800_000_000
        assert _parse_timestamp("2026-01-01T00:00:00", 0.0) == datetime(
            2026, 1, 1, tzinfo=timezone.utc
        ).timestamp()
    finally:
        monkeypatch.undo()
        time.tzset()