opencode-memory (Local-Memory-RAG)

Distributed local-first RAG memory layer and Event-Driven Knowledge Outcome Engine for opencode agents.

Keeps a persistent hybrid vector and keyword index of your per-project wiki markdown files. Distills conversation logs and workspace modifications into structured Knowledge Events (hypotheses, experiments, validations, failures, decisions, deprecations). Manages a persistent Concept Registry with strict lifecycle constraints (Candidate -> Emerging -> Validated -> Canonical -> Deprecated), materializing validated concept nodes and maintaining Obsidian-style bidirectional link graphs. Exposed as a globally accessible MCP server for every opencode session — with a gorgeous real-time visual console TUI inside your chat window.

---

How It Works

graph TB
    subgraph "Your Projects"
        YT["project-alpha/directives/wiki_*.md"]
        RS["project-beta/directives/design_wiki.md"]
        CO["wiki_concepts/concept_*.md (Validated Concepts)"]
        SE["sessions/YYYY-MM-DD.md (Events)"]
        REG["state/concept_registry.json"]
    end

    subgraph "opencode-memory Engine (~/.config/opencode/memory/)"
        engine["memory_mcp_server.py<br/>(FastMCP over stdio)"]
        core["memory_engine.py<br/>(Knowledge Engine & Search)"]
        tui["tui_renderer.py<br/>(Visual Console TUI)"]
        DB[".local_vector_db/ ChromaDB"]
        engine --> core
        engine --> tui
        core --> DB
    end

    subgraph "opencode Session"
        OC["opencode Agent"]
    end

    OC -- "tool: memory_session_start()" --> engine
    OC -- "tool: memory_session_commit()" --> engine
    OC -- "tool: memory_search()" --> engine
    OC -- "tool: memory_init_project()" --> engine

    core -.->|"extracts events"| SE
    core -.->|"updates lifecycle"| REG
    core -.->|"materializes validated nodes"| CO
    core -.->|"indexes hybrid search"| YT
    core -.->|"indexes hybrid search"| RS

Loading

Key Pillars

1. Dynamic Pre-Injection (Session Start) — On session startup, the agent reads progress logs, restores active goals/blockers, and preloads key historical concepts into its active brain state.
2. Knowledge Event Classification — Replaces raw note-taking with structured Knowledge Events capturing hypotheses, experiments, validations, failures, decisions, and deprecations inside YAML-formatted directives/sessions/YYYY-MM-DD.md reports.
3. Persistent Concept Registry — A central JSON registry (state/concept_registry.json) tracks concept IDs, canonical names, aliases, evidence count, session count, confidence, and lifecycle status. Resolves term variations and groups aliases semantically.
4. Strict Materialization Constraints — Prevents wiki directory pollution:
   • Candidate (seen in 1 session) & Emerging (seen in >= 2 sessions) remain in the registry only.
   • Validated (>= 3 evidence points) & Canonical (>= 5 sessions + >= 4 confidence) materialize full markdown nodes on disk.
   • Deprecated concepts automatically unlink core markdown files from disk.
5. ID-Based Reciprocal Graph Linking — Automatically inserting bidirectional Obsidian-style wikilinks referencing concept IDs [[concept_001|Canonical Name]] to maintain Obsidian graph density cleanly.
6. Sparse + Dense Hybrid Search — Integrates fast dense embeddings (BAAI/bge-small-en-v1.5 via ONNX) with pure-Python sparse keyword scoring (BM25) to guarantee 100% exact term accuracy.
7. Local & CPU-First — Powered by ChromaDB + fastembed over ONNX Runtime on CPU. Zero API costs and immediate warm-model performance.

---

Visual Console Panel Example

All tool results are formatted with professional terminal TUI styling:

╔══════════════════════════════════════════════════════════════════════╗
║                    Session Commit Complete | 🟢 SUCCESS               ║
╠══════════════════════════════════════════════════════════════════════╣
║ Master session commit succeeded.                                     ║
║ Report: 2026-06-01.md                                                ║
║                                                                      ║
║ Extracted Knowledge Events:                                          ║
║   - Hypothesis: 1 events                                             ║
║   - Experiment: 1 events                                             ║
║   - Validation: 1 events                                             ║
║   - Decision:   1 events                                             ║
║                                                                      ║
║ Graph & Index Evolution:                                             ║
║   Materialized:      1 concepts                                      ║
║   Bidirectional links: 2 links updated                               ║
║   Vector Index stats: 1 new, 0 updated chunks                        ║
╚══════════════════════════════════════════════════════════════════════╝

---

Quick Start

1. Clone the repo

git clone https://github.com/xpajonx/opencode-memory.git ~/.config/opencode/memory
cd ~/.config/opencode/memory

2. Create virtual environment & install dependencies

uv venv .venv
source .venv/bin/activate
uv pip install -r requirements.txt
uv pip install fastmcp

3. Index your projects

uv run python execution/memory_cli.py index

4. Register the MCP server in opencode

Add this to ~/.config/opencode/opencode.jsonc under "mcp":

"mcp": {
  "memory": {
    "type": "local",
    "command": ["uv", "run", "--directory", "/home/$USER/.config/opencode/memory", "python", "-m", "execution.memory_mcp_server"],
    "enabled": true,
    "timeout": 60000
  }
}

5. Restart opencode

The memory tools now appear automatically in your tool list.

---

Exposed Tools Summary

Tool Name	Parameters	Purpose / Behavior
memory_session_start	project	Reads local logs, auto-retrieves past context, preloads memories.
memory_reflect_session	project, conversation_text	Scans workspace and log to write structured YAML YYYY-MM-DD.md event reports.
memory_materialize_concepts	project	Updates Concept Registry lifecycles and materializes validated/canonical concept nodes.
memory_update_graph	project	Analyzes core nodes and establishes reciprocal bidirectional concept ID wikilinks.
memory_session_commit	project, conversation_text	Unified pipeline: runs reflection, concept registry lifecycle, graph linking, and indexing.
memory_search	query, k, project	BM25 sparse + dense semantic hybrid search across concept files.
memory_init_project	project, variant	Bootstraps the full Harness Framework 3-layer architecture tree.
memory_consolidate	project	Multi-file semantic deduplication and link graph cleaner.
memory_stats	(none)	Displays file counts, vector chunks, and database disk sizes.
memory_index	force	Triggers a delta or full indexing crawl across all projects.

---

CLI Usage (Manual Operations)

Still useful for quick configurations or local terminal executions:

# Unified Session Commit (reflect, materialize, bidirectional link, re-index)
uv run python execution/memory_cli.py session-commit project-name --chat "We verified that retrieval improved 18%."

# Bootstrap Harness framework in a new workspace
uv run python execution/memory_cli.py init new-project-name

# Run auto-prefetch at the start of a session
uv run python execution/memory_cli.py session-start project-name

# Perform Hybrid search (dense embeddings + sparse BM25)
uv run python execution/memory_cli.py search "buffer API configurations"

# Consolidate overlapping concepts / deduplicate notes
uv run python execution/memory_cli.py consolidate project-name

---

Testing

cd ~/.config/opencode/memory
uv run python -m unittest execution/test_memory.py