RFC-004 — Reference self wiki

• Status: Draft
• Authors: @yiidtw
• Created: 2026-05-14
• Supersedes: archive/003-claim-grounding.md (broader fact-check pipeline; cut)
• Numbering note: originally drafted as RFC-003 (unarchive of the claim-grounding RFC) but renumbered to 004 because 003-recording-orchestration.md landed on main first.

TL;DR

When the model is talking with the user, it should pull cites from ~/.amem/wiki/ on its own. Today the amem_recall and amem_cite MCP tools exist but the model only calls them when explicitly told. This RFC closes that gap with one prompt resource and one convenience tool.

Scope is small on purpose: just self-reference. No web dial-out, no LLM verifier, no clipper overlay, no iOS keyboard. Those were in the archived 003 and got cut because none of them needed to ship before the basic loop works.

Motivation — where the gap actually is

Anthropic already does grounding for things they can see:

What none of those touch: markdown files you wrote on your own disk. Anthropic can’t see ~/.amem/wiki/. MCP is the seam they left for it — and amem already exposes amem_recall + amem_cite over MCP.

The remaining gap is behavioural, not technical:

Today:  user says "what did I read on transformers"
        → model speculates from training data
        → only calls amem_recall if user types "@amem" or asks explicitly

Wanted: model auto-calls amem_recall when the topic is something the user
        might have captured, attaches amem:// cite when it hits, says
        nothing extra when it misses.

Proposal

1. MCP system_prompt resource

amem mcp serve exposes one resource:

URI:   amem://system/wiki-grounding
Mime:  text/plain
Body:
  When the user asks about a paper, dataset, technical spec, talk, or
  any source-able fact they might have captured, call `amem_recall`
  with the topic's key terms BEFORE answering from training data.

  - If a hit is returned: phrase the answer in terms of the wiki entry
    and append a cite "[<cite_key>](amem://<cite_key>)" so the user can
    click through. If they want BibTeX/APA/MLA, call `amem_cite`.

  - If no hit: answer normally from training knowledge. Do NOT invent
    a cite_key. Optionally suggest: "I don't see this in your wiki —
    want me to amem_capture <url>?"

  Skip recall for: code questions, logistics, jokes, opinions, the
  user's own preferences, very-well-known facts (e.g. "Python is dynamically typed").

MCP-aware clients (Claude Code, Cursor, Cline, Zed) merge resource content into the session system prompt automatically. No client patches.

2. New tool: amem_ground(query)

Single round-trip alternative to recall→cite chaining:

amem_ground(query: string, limit?: int) -> {
  hits: [{
    cite_key:   "vaswani2017attention",
    title:      "Attention Is All You Need",
    amem_uri:   "amem://vaswani2017attention",
    excerpt:    "...",
    bibtex:     "@article{vaswani2017attention, ...}"
  }],
  inline_md: "[Vaswani et al. 2017](amem://vaswani2017attention)"
}

Useful when the model knows it’ll cite (e.g. user asked a “what did the paper say” question). Saves one MCP round-trip vs. recall+cite separately.

3. amem:// URI scheme

Stable, filesystem-independent reference:

amem://<cite_key>               # whole wiki entry
amem://<cite_key>#chunk=<n>     # specific chunk (post-v0.1)

Plus a CLI handler so links in chat are clickable from terminal:

amem open amem://vaswani2017attention
  → opens ~/.amem/wiki/1776567380_vaswani2017attention.md in $EDITOR

What’s intentionally NOT in this RFC

These were in archived 003 and get pushed out:

If reference-self works and users want more, those come back in 004/005/… in their own RFCs, scoped tightly.

Verification — how we know it works

Two metrics from dogfooding (target: 1 week, 50+ conversations):

1. Call rate: of conversations that mention a topic the user has in wiki, what % auto-trigger amem_recall? Target: ≥60%. Below 30% = prompt too weak; strengthen. Above 90% in conversations without relevant wiki content = noisy; soften.
2. Hit rate: of amem_recall calls, what % return ≥1 hit? Target: ≥40%. Lower means model is searching too vaguely; refine the prompt’s “key terms” guidance.

Both numbers come from logging in amem-librarian MCP server (already logs recall calls; just need a daily summary).

Open questions

• Does MCP system_prompt resource actually flow into Claude Code’s prompt? Need to confirm against current Claude Code MCP behaviour. If resources don’t auto-merge, fallback is to bake the rule into each tool’s description field (every tool tells the model when to call it).
• Empty-result nudge: should amem_recall return {hits: [], suggest_capture: "<url>"} when it detects a URL-shaped query? Soft yes — turns misses into capture opportunities.
• Stale wiki entries: if you captured arxiv v1 in 2024 and the paper updated to v3, the cite is technically wrong. Out of scope for v0.1; flag for later.

Roll-out

No new infra. No client patches. Doesn’t block CWS submission of amem-clipper.

Rejected alternatives

• Auto-recall on every model turn — too noisy; would fire on “thanks” and “no”
• Background daemon scanning Claude transcripts — privacy + complexity for marginal gain
• Docs telling users to type @amem — that’s the current state; doesn’t work because nobody remembers
• Force model to cite something even on misses — turns into hallucinated cite_keys; worse than silence
• Ship as part of amem-clipper sidepanel UI — the gap is in Claude Code / Cursor / Cline, not the browser; clipper sidepanel doesn’t help