Agent memory UX: MCP surface + skills + doc pointers (epic)

[acgxv]

Context

• ELF is used primarily via MCP.
• ELF notes are intentionally compact; long-form memory is implemented via doc pointers + on-demand hydration.

Goals

• Enable long-form memory via doc pointers (in note source_ref) + hydration workflow.
• Make multi-agent shared memory operable via MCP (not HTTP-only).
• Ship reference agent-side workflows ("skills") so different agents behave consistently.

Status update (2026-02-25)

• Sharing/grants tools are exposed via MCP (elf_notes_publish, elf_notes_unpublish, elf_space_grants_*).
• Doc Extension v1 (PG SoT + Qdrant derived index + docs_put/docs_get/docs_search_l0/docs_excerpts_get) exists and has an end-to-end acceptance test.
• Multi-language strategy decision memo is completed (English-only server contract; upstream canonicalization; originals stored outside core notes).

Backlog (proposed child issues)

• Expose sharing + grants management via MCP (publish/unpublish, space grants list/upsert/revoke).
• Define a versioned source_ref doc-pointer schema (doc_id, uri, content_hash, locator/span, access hints).
• Add a document hydration component (Doc store + excerpt API) and an integration example.
• Ship a skills cookbook (doc_ingest, hydrate_context, write_policy, share_workflow, reflect_consolidate).
• Reflection/consolidation loop design + evaluation scenario(s).
• Provenance + observability standardization (trace correlation + provenance mapping).
• Multi-language strategy (English-only boundary vs upstream canonicalization + original text storage).

Open questions

1. Future doc backends: keep PG+Qdrant as default; track optional heavier backends separately.
2. Can agents connect to multiple MCP servers (e.g., elf-mcp + doc-mcp), or must everything be behind elf-mcp?

Notes

• Backlog draft captured in docs/plans/2026-02-23-agent-memory-mcp-skills-backlog.md.

Research links

• RAG: https://arxiv.org/abs/2005.11401
• MemGPT: https://arxiv.org/abs/2310.08560
• Generative Agents: https://arxiv.org/abs/2304.03442
• BEIR: https://arxiv.org/abs/2104.08663
• RRF: https://dl.acm.org/doi/10.1145/1571941.1572114
• Transactional outbox: https://microservices.io/patterns/data/transactional-outbox.html
• W3C PROV-DM: https://www.w3.org/TR/prov-dm/
• OpenTelemetry tracing spec: https://opentelemetry.io/docs/specs/otel/trace/

Child issues

• MCP: expose publish/unpublish + space grants tools #75
• Spec: versioned source_ref schema for doc pointers #76
• Doc hydration: doc store + excerpt API (and/or doc-mcp) #77
• Docs: skills cookbook for agent memory workflows (MCP-first) #78
• Research: reflection/consolidation loop + evaluation scenarios #79
• Observability: trace correlation + provenance mapping for memory flows #80
• Research: multi-language strategy for agent memory #81

[acgxv]

Doc-layer roadmap issues added (2026-02-24)

• Spec: Doc v1 Evidence Store contract (docs_put/docs_excerpts_get) + scope model (private/shared/public) #83 Spec: Doc v1 Evidence Store contract + scope model (private/shared/public)
• Doc ingest adapters: chat/search/dev history event types + deterministic chunking profiles #88 Doc ingest adapters: chat/search/dev history types + deterministic chunking profiles
• Doc retrieval: dense-first + optional sparse fusion + thread/time/type filters #84 Doc retrieval policy: dense-first + optional sparse fusion + filters
• Doc progressive disclosure: L0/L1/L2 excerpt levels + retrieval trajectory explain #85 Doc progressive disclosure: L0/L1/L2 excerpt levels + retrieval trajectory explain
• Doc derived views: on-demand excerpt translation cache (TTL, versioned, hash-keyed) #86 Doc derived views: on-demand excerpt translation cache (TTL, versioned)
• Research: OpenViking as optional doc backend (integration sketch + tradeoffs) #87 Research: OpenViking as an optional doc backend (integration sketch + tradeoffs)

These complement the existing doc-pointer/hydration work (#76, #77) and the language strategy work (#81).

[acgxv]

Decision update (2026-02-24)

• We are simplifying to an English-only contract across ELF memory and the planned Doc layer. Non-English content must be canonicalized upstream.
• As a result, server-side translation/caching (Doc derived views: on-demand excerpt translation cache (TTL, versioned, hash-keyed) #86) is deferred and multi-language strategy research (Research: multi-language strategy for agent memory #81) is closed as resolved by decision.