Module memory 

Durable semantic memory (v0.10.0).

Plain-Markdown, agent-managed long-term memory: one fact per file with YAML frontmatter (name, description, scope, created, tags) and a body. Three scopes, all machine-local except shared:

• global <data_dir>/memory/ (all projects)
• project-private <data_dir>/projects/<key>/memory/ (default; not committed)
• project-shared <git-root>/.mermaid/memory/ (opt-in; committed)

Retrieval is an always-loaded auto-derived INDEX (name + description + path per file, grouped by scope) plus on-demand reads of the full files via the normal read_file tool. The index is generated from the files, so it can never drift from them. No database, no vectors, no embeddings.

This module owns the on-disk format, scope resolution, index generation, load/refresh, and the write/delete primitives the memory tool and slash commands build on.

Structs

LoadedMemory

Snapshot of all loaded memory across scopes plus the rendered index block.

MemoryEntry

One memory file’s index entry. Deliberately holds no body — the full fact is read on demand via read_file on path, keeping the always-loaded snapshot small.

Enums

MemoryReloadOutcome

Outcome of a per-turn refresh(), for optional status reporting.

MemoryScope

Where a memory lives. The directory is authoritative; the frontmatter scope field is advisory/portable metadata so a hand-moved file is still classified by its location.

Functions

delete_memory

Delete a memory by name or file-stem id. Returns the deleted path, or None if no match.

dir_for

Resolve the on-disk directory for a scope at cwd, if available.

entries_with_bodies

Load every memory’s index entry paired with its full body text, across all scopes. Consolidation needs the bodies to judge duplicates/staleness.

find

Find a memory by name or file-stem id across all scopes.

find_git_root

Walk UP from start to the nearest directory containing a .git entry (file or dir, so worktrees resolve), or None if not inside a repo.

load

Load all memory for cwd into a snapshot, or None when disabled or empty.

memory_roots

The memory roots for cwd, in injection order (global → private → shared). Shared is omitted when cwd isn’t in a git repo. Returns an empty vec only if the machine data dir can’t be resolved.

refresh

Per-turn refresh: re-scan the roots (cheap — a few read_dirs + stats) and report whether anything changed since current. Picks up the agent’s own mid-session writes and hand edits with no filesystem watcher.

slugify

kebab-case slug for a memory name → filename stem.

write_memory

Write a memory at the resolved directory for scope/cwd.

write_to_dir

Write a memory into dir (created if needed). Returns the file path. Testable core of write_memory.