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

MemorySearchHit

One hit from a memory search: the matching entry plus a short excerpt of the line where the query matched (falling back to the description when the match is in the name/description rather than the body).

Enums

MemoryReloadOutcome

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

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.

search

Search all memory across scopes for query — a case-insensitive substring match over each fact’s name, description, and body. No embeddings or vectors (matches Mermaid’s stated stance); a plain scan over the already-bounded memory corpus. Bodies on disk are redacted at write time, so snippets are safe to surface. Returns an empty vec for a blank query.

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.