From 3e1fdc96dbb9688425e03164b24c7a5942eafcc6 Mon Sep 17 00:00:00 2001 From: Yvette Carlisle Date: Thu, 2 Jul 2026 23:57:13 -0400 Subject: [PATCH] {"schema":"decodex/commit/1","summary":"Codify source-backed project memory contract","authority":"XY-1151"} --- docs/index.md | 4 +- docs/log.md | 11 ++ docs/spec/agent_memory_knowledge_system_v1.md | 173 +++++++++++------- docs/spec/index.md | 2 +- 4 files changed, 125 insertions(+), 65 deletions(-) diff --git a/docs/index.md b/docs/index.md index 2ef5de6b..16d24a14 100644 --- a/docs/index.md +++ b/docs/index.md @@ -28,8 +28,8 @@ The split below is by question type, not by human-versus-agent audience. - Need contracts, invariants, schemas, enums, state machines, or required behavior -> `docs/spec/` -- Need the Agent Memory + Knowledge System product boundary, P0-P5 roadmap, - Decodex phase gate, or competitor absorption rules -> +- Need the source-backed project memory product boundary, P0-P5 roadmap, + Decodex phase gate, Context Pack/recall boundaries, or competitor absorption rules -> `docs/spec/agent_memory_knowledge_system_v1.md` - Need runbooks, migrations, validation steps, troubleshooting, or operational sequences -> `docs/runbook/` diff --git a/docs/log.md b/docs/log.md index fc20e60e..2b7b01c7 100644 --- a/docs/log.md +++ b/docs/log.md @@ -150,3 +150,14 @@ logs. checked-in snapshot covering 20 tracked products, including explicit VectifyAI PageIndex, VectifyAI OpenKB, and plastic-labs Honcho typed rows, without promoting any row to a universal product leaderboard claim. + +## 2026-07-03 + +- Updated `docs/spec/agent_memory_knowledge_system_v1.md` for XY-1151 to codify ELF + as open-source, source-backed project memory for AI agents. The revised contract + treats Source Library, Memory Authority, Source-to-Memory Authority loop, Knowledge + Workspace, Work Journal, Dreaming Review, Context Pack v1, Automatic Context + Routing, Recall Engine, Recall Debug, and benchmarks as supporting capabilities + rather than generic Knowledge OS scope. +- Updated docs routing so the retained spec path now resolves by the source-backed + project memory product name and explicit Context Pack/recall boundary language. diff --git a/docs/spec/agent_memory_knowledge_system_v1.md b/docs/spec/agent_memory_knowledge_system_v1.md index 070df71f..29d09031 100644 --- a/docs/spec/agent_memory_knowledge_system_v1.md +++ b/docs/spec/agent_memory_knowledge_system_v1.md @@ -1,87 +1,110 @@ --- type: Spec -title: "Agent Memory and Knowledge System v1" -description: "Define the ELF Agent Memory + Knowledge System product contract, roadmap, phase gate, and claim boundaries." +title: "Source-Backed Project Memory Product Contract v1" +description: "Define the ELF source-backed project memory product contract, roadmap, phase gate, and claim boundaries." resource: docs/spec/agent_memory_knowledge_system_v1.md status: active authority: normative owner: spec -last_verified: 2026-06-23 +last_verified: 2026-07-03 tags: - docs - spec - agent-memory - - knowledge -source_refs: [] + - project-memory +source_refs: + - https://linear.app/hack-ink/issue/XY-1150/elf-final-source-backed-project-memory-execution-program code_refs: - Makefile.toml related: - - docs/evidence/benchmarking/2026-06-20-agent-knowledge-os-closeout-benchmark-report.md - docs/evidence/benchmarking/2026-06-22-p1-memory-authority-closeout-report.md - docs/evidence/benchmarking/2026-06-23-p4-quality-hardening-productization-readiness-report.md - docs/runbook/benchmarking/real_world_agent_memory_benchmark.md - docs/spec/real_world_agent_memory_benchmark_v1.md - docs/spec/system_elf_memory_service_v2.md + - docs/spec/system_consolidation_proposals_v1.md - docs/spec/system_knowledge_pages_v1.md - docs/spec/system_recall_debug_panel_v1.md - docs/spec/system_graph_memory_postgres_v1.md - docs/spec/system_memory_summary_v1.md + - docs/spec/system_work_journal_v1.md drift_watch: - docs/spec/agent_memory_knowledge_system_v1.md - - docs/evidence/benchmarking/2026-06-20-agent-knowledge-os-closeout-benchmark-report.md - docs/evidence/benchmarking/2026-06-23-p4-quality-hardening-productization-readiness-report.md - docs/runbook/benchmarking/real_world_agent_memory_benchmark.md - Makefile.toml --- -# Agent Memory and Knowledge System v1 +# Source-Backed Project Memory Product Contract v1 -Purpose: Define the ELF Agent Memory + Knowledge System product contract, roadmap, +Purpose: Define the ELF source-backed project memory product contract, roadmap, phase gate, and claim boundaries. Status: normative Read this when: You are shaping product work, opening implementation issues, reviewing -Agent Memory + Knowledge System claims, or deciding which phase may be queued. +source-backed project memory claims, or deciding which phase may be queued. Not this document: Low-level service API semantics, benchmark fixture schemas, operator run commands, or implementation details for one subsystem. -Defines: `elf.agent_memory_knowledge_system/v1` product boundary, P0-P5 roadmap, -phase-gate rules, agent-facing surfaces, UI role, benchmark metrics, competitor -absorption rules, and phase closeout checklist. +Defines: `elf.source_backed_project_memory/v1` product boundary, P0-P5 roadmap, +phase-gate rules, agent-facing surfaces, benchmark metrics, competitor absorption +rules, and phase closeout checklist. ## Product Contract -ELF is an open-source Agent Memory + Knowledge System. +ELF is open-source, source-backed project memory for AI agents. -ELF turns sources into traceable knowledge, promotes reliable knowledge into agent -memory, and makes recall explainable, correctable, rollbackable, and benchmarked. +ELF lets agents remember project materials, decisions, progress, constraints, +preferences, and long-term context without requiring the user to re-explain the +project. Every important memory must have source provenance, freshness or lifecycle +status, history, reviewability, correction or rollback support, recall debugging, and +benchmark coverage for the claims made about it. -The lead wedge is source-linked memory authority plus recall/debug quality. ELF must -not be positioned as a generic RAG framework, wiki compiler, hosted memory SDK, -graph database, or document-search replacement. +Knowledge pages, Work Journal entries, Dreaming proposals, Context Packs, recall +routing, Recall Debug, and benchmarks exist to support source-backed project memory. +They are not separate product categories and must not expand ELF into a generic +Knowledge OS, broad RAG platform, Notion/OpenKB clone, hosted memory SDK, graph +database, or document-search replacement. ## System Boundary -The product is composed of six typed layers: +The product is composed of ten typed capabilities. Each capability supports the +source-to-memory authority chain and must keep its authority boundary visible in API, +MCP, UI, benchmark, and report surfaces. -| Layer | Authority | Required boundary | +| Capability | Authority | Required boundary | | --- | --- | --- | -| Source Library | Captured documents, excerpts, imports, and source refs. | Sources remain evidence. Derived memory and pages must cite sources instead of replacing them. | -| Memory Authority | Notes, core blocks, ingest decisions, history, corrections, and rollback evidence. | Memory writes are policy-gated, evidence-linked, auditable, and reversible. | -| Knowledge Workspace | Derived project, entity, concept, issue, decision, author, and timeline pages. | Pages are rebuildable derived artifacts with citations, lint, and stale-source detection. | -| Graph-lite Facts | Postgres-backed relation facts and temporal markers. | Graph facts are source-backed context, not a separate authority store. | -| Dreaming Review | Reviewable consolidation, summary, brief, tag, correction, and promotion proposals. | Derived proposals must be reviewable and must not mutate sources without an explicit accepted transition. | -| Recall Debug | Search traces, dropped candidates, source/doc/page/graph/proposal rows, and replay aids. | Recall must expose why context was selected, dropped, unavailable, blocked, or not requested. | +| Source Library | Captured project documents, excerpts, imports, source snapshots, and source refs. | Sources remain evidence. Derived memory, pages, proposals, and packs must cite sources instead of replacing them. | +| Memory Authority | Notes, core blocks, ingest decisions, history, corrections, and rollback evidence. | Current memory writes are policy-gated, evidence-linked, auditable, and reversible. | +| Source-to-Memory Authority Loop | Candidate creation, review, approval, promotion, correction, and rollback transitions. | A source, journal row, page section, graph fact, or proposal is not current memory until promoted through the authority path. | +| Knowledge Workspace | Derived project, entity, concept, issue, decision, author, and timeline pages. | Pages are rebuildable supporting artifacts with citations, lint, and stale-source detection; they are not authoritative memory hits. | +| Work Journal | Source-adjacent session logs, handoff briefs, janitor reports, next steps, and rejected options. | Journal-only facts can answer continuity questions but must not become current project authority without accepted promotion evidence. | +| Dreaming Review | Reviewable consolidation, summary, brief, tag, correction, routing, and promotion proposals. | Dreaming may propose and organize; it must not silently mutate sources or current memory. | +| Context Pack v1 | Bounded, cited bundles assembled for an agent task from current readable sources, memory, pages, traces, and proposals. | Context Packs are transport artifacts, not shadow memory; they expire or rebuild from authorities and must not create facts by packaging them. | +| Automatic Context Routing | Deterministic or constrained model-assisted selection of which authority layers and pack scopes a task should inspect. | Routing may choose surfaces and pack budgets; it must expose rationale and must not bypass scope, lifecycle, review, or evidence rules. | +| Recall Engine | Search, expansion, rerank, relation context, source/page/journal retrieval, and pack assembly. | Recall returns typed context with freshness and authority labels; derived or blocked context must not be narrated as current authority. | +| Recall Debug | Search traces, dropped candidates, source/doc/page/journal/graph/proposal rows, replay aids, and pack/routing explanations. | Recall must expose why context was selected, dropped, stale, unavailable, blocked, or not requested. | Existing subsystem specs own their detailed contracts. This document owns how those -subsystems fit into the Agent Memory + Knowledge System product boundary. +subsystems fit into the source-backed project memory product boundary. ## Non-Goals +- Do not build or position ELF as a generic Knowledge OS, broad RAG clone, generic + Notion/OpenKB clone, hosted memory SDK, graph database, or document-search + replacement. +- Do not make Memory Experts the user-facing product concept. User-facing language + should name source-backed project memory and the typed supporting capabilities. +- Do not let Dreaming silently mutate sources, current memory, authority history, + corrections, or published knowledge pages. +- Do not treat journal-only facts as current project authority. +- Do not let Context Packs become shadow memory or an uncited source of durable facts. +- Do not make broad market-leadership, universal leaderboard, private-corpus, + provider-backed, hosted, UI/export, graph/RAG, core/archive, context-trajectory, or + long-document parity claims without comparable product-runtime evidence for the + exact claim. - Do not turn ELF into a broad RAGFlow, OpenKB, PageIndex, mem0, Zep, Letta, qmd, - OpenViking, agentmemory, claude-mem, or memsearch replacement. + OpenViking, agentmemory, claude-mem, memsearch, Graphiti, Zep, GraphRAG, or + LightRAG replacement. - Do not weaken Postgres source-of-truth, source-ref, evidence-binding, English-gate, scope, lifecycle, or review boundaries to match another product's ergonomics. -- Do not claim hosted managed-memory, private-corpus, provider-backed, UI/export, - graph/RAG, core/archive, context-trajectory, or long-document parity without - same-corpus checked-in or operator-owned evidence for that exact claim. - Do not collapse `blocked`, `incomplete`, `not_encoded`, `wrong_result`, or `unsupported_claim` states into pass claims. - Do not queue later phases while the current accepted phase is still under review. @@ -92,40 +115,46 @@ All implementation phases must preserve the source-to-memory authority chain: 1. Sources are captured as documents, excerpts, event audits, issue/PR records, or other source refs with stable provenance. -2. Candidate knowledge is derived from sources as proposals, page sections, graph - facts, summaries, or memory candidates. +2. Candidate project memory is derived from sources as proposals, page sections, + journal entries, graph facts, summaries, routing evidence, Context Pack inputs, or + memory candidates. 3. Promotion into memory records an explicit policy decision, source refs, actor, confidence, importance, lifecycle state, and audit trail. 4. Correction and rollback create durable history instead of silently rewriting the evidence chain. -5. Recall reads from typed surfaces and returns enough trace data to debug selection, - demotion, filtering, staleness, and missing anchors. +5. Recall reads from typed authority or support surfaces and returns enough trace data + to debug selection, demotion, filtering, staleness, routing, pack assembly, and + missing anchors. Postgres remains the authority for notes, docs metadata, graph-lite facts, derived -pages, proposal review state, traces, and audit history. Qdrant and any future -retrieval index remain derived and rebuildable. +pages, Work Journal entries, Dreaming review state, Context Pack manifests, routing +traces, recall traces, and audit history. Qdrant and any future retrieval index +remain derived and rebuildable. ## Agent-Facing Surfaces Agent-facing tools must be thin MCP or HTTP facades over typed service behavior. Business logic and policy remain in `elf-api` and `elf-service`. -Current and future Agent Memory + Knowledge System work should use these surface +Current and future source-backed project memory work should use these surface families: | Surface family | Examples | Boundary | | --- | --- | --- | | Source capture and hydration | `elf_docs_put`, `elf_docs_search_l0`, `elf_docs_excerpts_get` | Capture and retrieve source evidence without promoting it to memory by default. | | Memory write and readback | `elf_notes_ingest`, `elf_events_ingest`, `elf_searches_create`, `elf_searches_notes`, `elf_core_blocks_get`, `elf_entity_memory_get` | Writes must preserve policy and evidence decisions; reads must honor scopes and lifecycle. | +| Source-to-memory review | Memory candidate, consolidation proposal, correction, and review surfaces | Promote or correct current memory only through explicit accepted authority transitions. | +| Work continuity | Work Journal capture and readback surfaces | Answer continuity from source-adjacent evidence while keeping journal-only facts out of current authority. | | Provenance and history | `elf_admin_note_provenance_get`, `elf_admin_memory_history_get`, trace bundle tools | Debug memory authority without raw database access in normal workflows. | -| Knowledge and graph context | Knowledge page search/readback, `elf_graph_query`, graph report surfaces | Expose derived knowledge and graph facts as labeled context, not authoritative note hits. | +| Knowledge and graph context | Knowledge page search/readback, `elf_graph_query`, graph report surfaces | Expose derived pages and graph facts as labeled context, not authoritative note hits. | | Dreaming review | Dreaming review queue and proposal review surfaces | Keep proposals reviewable; auto-apply is limited to explicitly accepted low-risk derived organization cases. | -| Recall debug | `elf_recall_debug_panel`, trace and trajectory readback | Show selected, dropped, available, reviewable, blocked, and not-requested context. | +| Context Packs and routing | Context Pack v1 creation/readback and automatic routing traces | Assemble bounded cited context for a task without creating shadow memory or bypassing authority. | +| Recall and Recall Debug | Recall Engine readback, `elf_recall_debug_panel`, trace and trajectory readback | Show selected, dropped, available, reviewable, blocked, and not-requested context. | New MCP tools must name the underlying authority layer, link to the owning spec, and preserve read/write boundaries. A readback tool must not become a hidden mutation path. -## UI Role +## Operator UI Role The UI is an operator console for source review, memory authority, knowledge pages, proposal review, graph/topic inspection, and recall debugging. @@ -143,6 +172,26 @@ The UI must: The UI is not the source of truth and must not bypass API, MCP, scope, review, or write-policy contracts. +## Execution Program + +The execution program is split into Decodex-trackable implementation slices so +cold-start lanes can work from their issue briefs plus this spec. The source issue +for this program is `XY-1150`. + +| Issue | Slice | Required result | +| --- | --- | --- | +| XY-1151 | Product contract | Specs state the final source-backed project memory positioning, supporting capabilities, and non-goals. | +| XY-1152 | Source Library and Memory Authority | Implement the lifecycle model for source evidence, authoritative memory, source-to-memory promotion, correction, and rollback. | +| XY-1153 | Knowledge Workspace, Work Journal, and Dreaming | Implement derived knowledge, source-adjacent continuity, and reviewable proposal boundaries without silent authority mutation. | +| XY-1154 | Context Pack v1, automatic routing, Recall Engine, and Recall Debug | Implement cited task packs, routing rationale, typed recall, and trace/debug readback. | +| XY-1155 | Benchmark harness | Produce executable tests, executable benchmarks, and benchmark artifacts for source-backed memory quality. | +| XY-1156 | qmd candidate-replay comparability gate | Preserve qmd replay/debug comparability until ELF emits comparable artifacts. | +| XY-1157 | Independent review and closeout | Run independent review/skeptic gates, fix P0/P1 findings, and publish final readiness evidence. | + +These issues may execute independently only within their accepted issue scope. They +must not use Program graph ids, queue labels, or private runtime state as execution +authority. + ## Roadmap The roadmap phases below are product phases. They are not broad permission to queue or @@ -150,12 +199,12 @@ implement every item in a phase at once. | Phase | Name | Scope | Gate to leave phase | | --- | --- | --- | --- | -| P0 | Product contract and phase gate | Codify this product boundary, roadmap, competitor absorption rules, validation expectations, and closeout checklist. | Docs are reviewed, repo docs validation passes, claim boundaries match the June 20 closeout evidence, and the main thread accepts the next phase. | -| P1 | Memory Authority MVP loop | Deliver one source-backed memory-authority vertical slice: capture source evidence, create/review one proposal through a proposal inbox, record the authority ledger, apply/correct/rollback, recall through agent-facing tools, and debug stale/correction behavior. | The slice has service tests, provenance/history evidence, recall/debug readback, and at least one real-world stale/correction benchmark job. | -| P2 | Knowledge Workspace | Promote source-linked project/entity/concept/issue/decision/author/timeline pages with rebuild, lint, watch, search, and version-diff readback. | Pages stay derived, every section is cited or explicitly unsupported, stale-source lint runs, and benchmark reports publish citation/staleness metrics. | -| P3 | Competitor-strength adapters | Add contained comparison adapters for qmd replay, PageIndex/OpenKB, mem0/OpenMemory, Letta, Graphiti/Zep, OpenViking, graph/RAG references, and other accepted deltas. | Each adapter preserves typed non-pass states and emits same-corpus evidence or a concrete typed setup blocker before any parity, win, tie, or loss claim. | -| P4 | Benchmark and quality hardening | Expand adversarial jobs, public comparison grammar, quality metrics, latency/cost/resource reporting, and unsupported-claim detection. | Reports preserve job/suite/project typed states, expected evidence recall, irrelevant context ratio, unsupported claims, and resource metrics. | -| P5 | Productization | Improve local setup, agent recipes, operator UI, privacy/delete/export boundaries, and production-quality workflows. | Operator workflows have documented setup, privacy/delete/export semantics, and validation evidence without weakening source authority. | +| P0 | Product contract and phase gate | Codify source-backed project memory positioning, capability boundaries, competitor absorption rules, validation expectations, and closeout checklist. | Docs are reviewed, repo docs validation passes, claim boundaries reject generic Knowledge OS/RAG clone positioning, and the main thread accepts the next phase. | +| P1 | Source Library and Memory Authority loop | Deliver one source-backed memory-authority vertical slice: capture source evidence, create/review one proposal through a proposal inbox, record the authority ledger, apply/correct/rollback, recall through agent-facing tools, and debug stale/correction behavior. | The slice has service tests, provenance/history evidence, recall/debug readback, and at least one real-world stale/correction benchmark job. | +| P2 | Knowledge, Journal, and Dreaming boundaries | Promote source-linked project/entity/concept/issue/decision/author/timeline pages, Work Journal continuity, and Dreaming proposal review with rebuild/lint/watch/search/version-diff readback where applicable. | Pages stay derived, journal-only facts stay non-authoritative, Dreaming does not silently mutate authority, stale-source lint runs, and benchmark reports publish citation/staleness metrics. | +| P3 | Context and Recall | Deliver Context Pack v1, Automatic Context Routing, Recall Engine behavior, and Recall Debug traces. | Packs are bounded and cited, routing exposes rationale, recall labels authority and freshness, and debug traces preserve selected/dropped/blocked/not-requested evidence. | +| P4 | Benchmark and quality hardening | Expand executable benchmarks, qmd candidate-replay comparability, adversarial jobs, public comparison grammar, quality metrics, latency/cost/resource reporting, and unsupported-claim detection. | Reports preserve job/suite/project typed states, expected evidence recall, irrelevant context ratio, unsupported claims, qmd replay comparability, and resource metrics. | +| P5 | Productization | Improve local setup, agent/MCP recipes, operator UI, privacy/delete/export boundaries, and production-quality workflows. | Operator workflows have documented setup, privacy/delete/export semantics, and validation evidence without weakening source authority. | ### First Implementation Phase Constraint @@ -183,17 +232,13 @@ Decodex execution for this project is single-phase gated: to start additional phases. - `In Review` is a PR-backed handoff state. It is not phase acceptance by itself. -As of the June 22, 2026 XY-1063 closeout, P1 has fixture-backed self-assessment -evidence for the memory-authority MVP loop. P2 queueing remains conditional on -main-thread acceptance of that closeout and selection of one narrow next P2 issue. +As of the July 2026 XY-1150 source issue, the accepted execution direction is an +open-source, source-backed project memory system for AI agents. Generated Decodex +issues XY-1151 through XY-1157 are the implementation slices for that direction. -As of the June 23, 2026 XY-1075 closeout, P4 has fixture-backed quality hardening -and production-readiness self-assessment evidence across adversarial memory, -Source Library, Knowledge Workspace, and production-ops slices. P5 productization -work may be queued only after main-thread acceptance of that closeout, and only for -the proven local/public workflows named there. Private-corpus quality, -provider-backed quality, hosted managed-memory parity, external adapter parity, and -broad competitor superiority remain unqueued until their own evidence gates pass. +Earlier Agent Knowledge OS, P1, P2, P3, and P4 reports remain evidence anchors for +specific measured capabilities only. They do not authorize generic Knowledge OS +positioning, broad RAG clone scope, or unsupported product-leadership claims. ## Competitor Absorption Rules @@ -214,15 +259,19 @@ dependencies and are not automatic proof that ELF is weaker or stronger. Allowed claims: -- ELF is the strongest measured integrated Agent Knowledge OS product in the June 20, - 2026 checked-in matrix. -- ELF has complete same-repo evidence across the six Agent Knowledge OS layers in - that matrix. +- ELF is open-source, source-backed project memory for AI agents when the claimed + surface has implementation, tests, and source-backed evidence. +- ELF has checked-in evidence for specific measured slices named by their reports, + such as Memory Authority, Source Library, Knowledge Workspace, Work Journal, + Dreaming review, Recall Debug, production-readiness gates, and public quantitative + scoreboard rows. - Competitor strengths remain optimization inputs and comparison targets. Disallowed claims: - ELF broadly beats every competitor on every competitor-owned strength. +- ELF is a generic Knowledge OS, generic RAG platform, generic wiki compiler, Notion + clone, hosted managed memory platform, or broad knowledge-everything product. - Reference-only, blocked, incomplete, wrong-result, or not-tested evidence is a pass. - Public-proxy or local fixture evidence proves private-corpus or provider-backed production quality. diff --git a/docs/spec/index.md b/docs/spec/index.md index c250b89c..4e4a15ca 100644 --- a/docs/spec/index.md +++ b/docs/spec/index.md @@ -32,7 +32,7 @@ Question this index answers: "what must remain true?" ## Documents - `agent_memory_quantitative_benchmark_v1.md`: Agent Memory Quantitative Benchmark v1. -- `agent_memory_knowledge_system_v1.md`: Agent Memory and Knowledge System v1. +- `agent_memory_knowledge_system_v1.md`: Source-Backed Project Memory Product Contract v1. - `external_memory_pattern_radar_v1.md`: External Memory Pattern Radar v1. - `production_corpus_manifest_v1.md`: Production Corpus Manifest v1. - `real_world_agent_memory_benchmark_v1.md`: Real-World Agent Memory Benchmark v1.