ReMe/reme2/memory/protocol.md

Memory Protocol

Single source of truth for vault schema, conventions, and the R-M-W write loop. Consumed by:

• Ingestor's embedded ReAct prompt (reme2/memory/ingestor.yaml — injected as {protocol} at load time).
• Strong-agent SKILL (reme-plugin/skills/reme/SKILL.md — transcluded so the host agent sees the same rules).

Anything that defines schema invariants, path templates, write tool semantics, or the R-M-W decision tree belongs here. Anything role- specific (caller framing, audit trail expectations, summary requirements) stays in the consumer.

Vault layout

• Topics — long-lived cognitive memory at topics/{folder}/{name}.md. A folder topic has folder == name; it's the cluster's index head. Short wikilink [[X]] resolves to the folder topic if one exists, else falls back to a unique same-stem file.
• Events — fact log of one session at events/{YYYY-MM-DD}/{name}/{name}.md. The .md is the index inside a folder; sibling files are materials (raw conversation, tool outputs, data dumps). The index lists them under ## Materials.

Frontmatter — 4 schema axes

Every memory declares 4 orthogonal axes. The legacy category field is auto-translated to these axes for back-compat reads, but new writes should set the axes directly.

Axis	Values	Meaning
lifecycle	streaming / evolving / frozen	streaming = events (decay/archive); evolving = topics (long-lived, edited); frozen = materials (immutable references)
scope	instance / class	instance = a specific moment / object; class = abstract concept / role / pattern
source	auto / curated / derived	auto = system-captured; curated = human/LLM intent; derived = computed from other memories
role	observation / claim / question / profile / concept / method / reference / fundamentals	cognitive role — drives ranking + role-specific validation

Conditional fields

• confidence ∈ {⏳, ✅, ❌} — REQUIRED when role: claim (legacy categories thesis / model). Same gate applies to role: question (legacy questions).
• status ∈ {active, distilled, archived} — meaningful only for lifecycle: streaming. Topic-style memories ignore it.
• originSessionId — should be set when source: auto.

Standard identity fields

title, description, tags, created, updated, topics, parent. Use today's date for created / updated on new writes.

Cross-file references

[[wikilink]] syntax. Two forms:

• Stem form [[X]] — resolved against the file_store's stem index; prefers the folder topic if one exists.
• Path form [[topics/X/X]] or [[topics/X/X.md]] — anchored at the vault root.

Status state machine

active → distilled → archived (single direction, no skip). A reverse or skip transition will be flagged by the Maintainer.

Wikilink uniqueness

Every create path routes through MemoryCreate.write, which refuses to introduce ambiguity (existing [[X]] would resolve to ≥2 paths). When rejected, the response includes a suggested_name. Retry with that, or pick a domain-specific qualifier (Apple-Inc beats Apple-2). Never bypass with force=true unless you fully understand the ambiguity.

Available tools

Read tools (gather context BEFORE writing)

• memory_get(path, include_chunks=False) — full file content + frontmatter. On an event index, follow ## Materials and read each artifact whose content you need.
• memory_list(path_prefix=None, tags=None, metadata=None, limit=100) — list indexed files filtered by prefix / tags / frontmatter.
• memory_resolve_wikilink(wikilink) — resolve [[X]] to a path; flags ambiguity / dangling.
• memory_backlinks(path) — files linking TO the given path.
• memory_links(path) — files the given path links to.
• memory_search(query, …) — hybrid (vector + keyword) chunk search.
• memory_graph_search(query, seeds, graph_depth, …) — vector + keyword + graph BFS fusion.

Write tools (mutations are SSOT-routed; each returns success +

payload + records to audit)

• memory_update(path, old_string, new_string, replace_all=False) — body edit by exact-string substitution. Use a tail snippet to append.
• memory_property_update(path, key, value) — change one frontmatter key (value=null deletes). Use this to flip status.
• memory_create(path, metadata, content, overwrite=False, force=False) — new file. Reserve for genuinely NEW topics. Do NOT use for events (sync owns events). All paths must be ABSOLUTE under vault_root.
• memory_rename(old_path, new_path) — move file + rewrite cross-vault wikilinks. Refuses on destination conflict or stem ambiguity.
• memory_delete(path) — remove a file.
• memory_archive(path) — flip status: archived and move under <vault>/Archive/.

Hot-write helper (deterministic, no LLM)

• sync(name, description?, content?, topics?, tags?, materials?, on_date?) — idempotent upsert of an event FOLDER per (date, name). Reuse the same name across calls in one thread to keep extending the same folder. Refuses on status: distilled / archived and returns a suggested_name.

R-M-W decision rules

Apply in order. Stop at the first match.

1. SKIP — if material is ALREADY covered by existing topics, reply with a single line SKIP: <one-line reason> and call no tools.
2. CONTRADICT — if material CONTRADICTS an existing block, use memory_update with a unique snippet of the outdated text and the corrected replacement.
3. EXTEND — if material EXTENDS an existing topic, use memory_update with a unique TAIL snippet of the existing body, and new_string = tail + blank line + new content.
4. CREATE — if material warrants a GENUINELY NEW topic, use memory_create at topics/{folder}/{name}.md. Do NOT memory_create under events/ — sync owns that path.
5. STATUS FLIP — after integrating an event's content into a topic, flip that event's status to distilled with memory_property_update.

Operating principles

• Read before write. Always inspect related topics before deciding CONTRADICT vs EXTEND vs CREATE. The wikilink-uniqueness gate refuses blind creates; reading first prevents wasted attempts.
• Minimal edits. Edit only what must change. Don't restructure while updating content.
• Frontmatter on create. Always include reasonable frontmatter: the 4 axes, title, created, updated, plus confidence when role: claim or role: question.
• Never delete unless asked. Distillation flips status; it does not remove events.