MEMORY: engine — typed memory model + multi-signal recall

[Hmbown]

Part of #534 (Phase 3 EPIC). Builds on #535 (substrate).

Thesis

Treat memories as typed records, not lines in a file. Different kinds of memory have different lifecycles and different rules for promotion, decay, and recall. Recall scores candidates by recency + salience + access frequency + scope match, not raw text grep — and returns explanation strings so users can see why a memory was surfaced.

Memory types

Initial taxonomy (extensible):

Type	Example
semantic	"the API base URL is api.deepseek.com"
episodic	"user rejected the autoformat-on-save proposal in this session"
procedural	"to deploy: cargo build --release && scp …"
reflective	"last refactor of compaction.rs broke working_set tests — be cautious"
intentional	"next step: wire moontree-style memory"
constitutional	"this user prefers explicit error handling over unwrap"
restriction	"never run git push --force without confirming"

Recall ranking

Score = w_text * fts5_rank + w_recency * recency_decay + w_salience * salience + w_frequency * log(access_count) + w_scope * scope_match.

Each hit returns a RecallHit { memory, score, explanation: "matched 'compaction' (FTS) + accessed 4× this session + recent" }. Users see why something was surfaced; this is also debuggable.

Concrete

• Memory record schema in crates/tui/src/memory/model.rs.
• Recall function in crates/tui/src/memory/recall.rs.
• Replace tools/recall_archive.rs BM25 with the new ranker.
• /memory UI surfaces type as a column.
• Existing flat-file content imports as semantic by default.
• No embeddings in this issue — FTS5 + signals first. Reopen for vectors only if quality wall hit.

Open questions

• Which types does the model write directly (via a tool call) vs which are auto-classified by the extraction subagent (#E)?
• How aggressive is salience decay? Half-life of 30 days? 7? Per-type?
• Default weights for the recall scoring function.

Acceptance signals

• recall(query, scope) returns ranked, typed results with explanations.
• /memory UI surfaces type and recall score.
• Recall regression: a fixture set of memories + queries produces stable rankings across runs.
• Existing flat-file content survives migration as semantic memories.

[merchloubna70-dot]

The multi-signal recall part of this issue (recency + semantic similarity + access frequency) is already handled by mem0's retrieval layer — it scores candidates using vector similarity + LLM re-ranking before returning results.

The typed memory classes (semantic / episodic / procedural / reflective…) are not in mem0 OSS, but that's a thin classification layer (~100 lines of Rust) that could sit on top of mem0's add_memory tool, tagging records with a type metadata field.

This approach would cut the implementation scope significantly compared to building the full engine from scratch. Full proposal with mcp.json config in #534.

---

wangfengcsu@qq.com