Agent 06：一个简单实现（4）Memory

~/.claude/memory/
  MEMORY.md                    # 索引文件，每行一条指针
  user_role.md                 # 独立记忆文件
  feedback_testing.md           # 独立记忆文件
  project_auth_rewrite.md      # 独立记忆文件
  reference_linear_project.md  # 独立记忆文件

- [name1](file1.md) - description
- [name2](file2.md) — description
...

# Maximum lines/bytes for the index file
MAX_INDEX_LINES = 200
MAX_INDEX_BYTES = 25_000

# 截断函数中，找到上限之前的最后一个换行符，以免切断一条记忆的中间
if len(truncated.encode()) > MAX_INDEX_BYTES:
        # Cut at last newline before byte limit
        raw_bytes = truncated.encode()
        cut = raw_bytes[:MAX_INDEX_BYTES].rfind(b"\n")
        truncated = raw_bytes[: cut if cut > 0 else MAX_INDEX_BYTES].decode(errors="replace")

class MemoryEntry:
    """A single memory entry loaded from a .md file.

    Attributes:
        name:        human-readable name (also the display title in the index)
        description: short one-line description (used for relevance decisions)
        type:        "user" | "feedback" | "project" | "reference"
        content:     body text of the memory
        file_path:   absolute path to the .md file on disk
        created:     date string, e.g. "2026-04-02"
        scope:       "user" | "project" — which directory this was loaded from
    """
    name: str
    description: str
    type: str
    content: str
    file_path: str = ""
    created: str = ""
    scope: str = "user"

---
name: {{memory name}}
description: {{one-line description — used to decide relevance, so be specific}}
type: {{user | feedback | project | reference}}
---

{{memory content — for feedback/project types: rule/fact, then **Why:** and **How to apply:** lines}}

---
name: feedback_testing
type: feedback
scope: user
description: Integration tests must hit a real DB, not mocks
---

Don't mock the database in tests.
**Why:** mocks hide query/schema bugs until prod.
**How to apply:** when writing tests that touch the DB layer, spin up the test DB instead of using unittest.mock.

class MemoryHeader:
    """Lightweight descriptor loaded from a memory file's frontmatter.

    Attributes:
        filename:    basename of the .md file
        file_path:   absolute path
        mtime_s:     modification time (seconds since epoch)
        description: value from frontmatter `description:` field
        type:        value from frontmatter `type:` field
        scope:       "user" or "project"
    """
    filename: str
    file_path: str
    mtime_s: float
    description: str
    type: str
    scope: str

def scan_memory_dir(mem_dir: Path, scope: str) -> list[MemoryHeader]:
    """Scan a single memory directory and return headers sorted newest-first.

    Reads only the frontmatter (first ~30 lines) for efficiency.
    Silently skips unreadable files. Caps at MAX_MEMORY_FILES entries.
    """
    if not mem_dir.is_dir():
        return []

    headers: list[MemoryHeader] = []
    for fp in mem_dir.glob("*.md"):
        if fp.name == INDEX_FILENAME:
            continue
        try:
            stat = fp.stat()
            # Read only the first 30 lines for frontmatter
            lines = fp.read_text(errors="replace").splitlines()[:30]
            snippet = "\n".join(lines)
            meta, _ = parse_frontmatter(snippet)
            headers.append(MemoryHeader(
                filename=fp.name,
                file_path=str(fp),
                mtime_s=stat.st_mtime,
                description=meta.get("description", ""),
                type=meta.get("type", ""),
                scope=scope,
            ))
        except Exception:
            continue

    headers.sort(key=lambda h: h.mtime_s, reverse=True)
    return headers[:MAX_MEMORY_FILES]

def format_memory_manifest(headers: list[MemoryHeader]) -> str:
    """Format a list of MemoryHeader as a text manifest.

    Format per line:  [type/scope] filename (age): description
    Example:
        [feedback/user] feedback_testing.md (3 days ago): Don't mock DB in tests
        [project/project] project_freeze.md (today): Merge freeze until 2026-04-10
    """
    lines = []
    for h in headers:
        tag = f"[{h.type}/{h.scope}]" if h.type else f"[{h.scope}]"
        age = memory_age_str(h.mtime_s)
        if h.description:
            lines.append(f"- {tag} {h.filename} ({age}): {h.description}")
        else:
            lines.append(f"- {tag} {h.filename} ({age})")
    return "\n".join(lines)

// src/memdir/findRelevantMemories.ts, 第 18-24 行
const SELECT_MEMORIES_SYSTEM_PROMPT = `You are selecting memories that will be useful to Claude Code as it processes a user's query. You will be given the user's query and a list of available memory files with their filenames and descriptions. Return a list of filenames for the memories that will clearly be useful (up to 5). Only include memories that you are certain will be helpful...`

register_tool(ToolDef(
    name="MemorySearch",
    schema={
        "name": "MemorySearch",
        "description": (
            "Search persistent memories by keyword. Returns matching entries with "
            "content preview and staleness warning for old memories. "
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "Search query"},
                "max_results": {
                    "type": "integer",
                    "description": "Maximum results to return (default: 5)",
                },
                "scope": {
                    "type": "string",
                    "enum": ["user", "project", "all"],
                    "description": "Which scope to search (default: 'all')",
                },
            },
            "required": ["query"],
        },
    },
    func=_memory_search,
    read_only=True,
    concurrent_safe=True,
))

def memory_age_days(mtime_s: float) -> int:
    """Days since mtime_s (floor-rounded, clamped to 0 for future times)."""
    return max(0, math.floor((time.time() - mtime_s) / 86_400))


def memory_age_str(mtime_s: float) -> str:
    """Human-readable age: 'today', 'yesterday', or 'N days ago'."""
    d = memory_age_days(mtime_s)
    if d == 0:
        return "today"
    if d == 1:
        return "yesterday"
    return f"{d} days ago"

def memory_freshness_text(mtime_s: float) -> str:
    """Staleness caveat for memories older than 1 day (empty string if fresh).

    Motivated by user reports of stale code-state memories (file:line
    citations to code that has since changed) being asserted as fact.
    """
    d = memory_age_days(mtime_s)
    if d <= 1:
        return ""
    return (
        f"This memory is {d} days old. "
        "Memories are point-in-time observations, not live state — "
        "claims about code behavior or file:line citations may be outdated. "
        "Verify against current code before asserting as fact."
    )

// src/memdir/memoryTypes.ts, 第 240-256 行
export const TRUSTING_RECALL_SECTION: readonly string[] = [
  '## Before recommending from memory',
  '',
  'A memory that names a specific function, file, or flag is a claim that ' +
  'it existed *when the memory was written*. It may have been renamed, ' +
  'removed, or never merged. Before recommending it:',
  '',
  '- If the memory names a file path: check the file exists.',
  '- If the memory names a function or flag: grep for it.',
  '- If the user is about to act on your recommendation: verify first.',
  '',
  '"The memory says X exists" is not the same as "X exists now."',
]