Memory

Memory

Persistent memory across sessions using ChromaDB vector search. Every conversation is stored and retrievable.

How It Works

The memory system uses ChromaDB (local vector database, no server needed) to store conversation context as embeddings. When you start a new session, the agent searches past memory for relevant context.

• Storage: ~/.shokunin/memory/chroma_db/ (ChromaDB persistent files)
• Sessions: ~/.shokunin/memory/sessions/ (markdown summaries per session)
• MCP Server: ~/.shokunin/memory/mcp-server.py

Workflow

Step 1: Start memory server (if not running)

The memory MCP server is configured in opencode.json. It starts automatically when OpenCode connects to it.

Step 2: Save context during session

At the end of each significant task, save context:

store_context with:
  text: "Summary of what was done, key decisions, code patterns"
  tags: ["project-name", "feature", "language"]
  project: "project-name"
  session_id: "current-session-id"

Step 3: Search past memory at session start

When starting a new session, search for relevant context:

search_context with:
  query: "what we discussed about auth"
  project: "current-project"

Step 4: Get full session summary

get_session_summary with:
  session_id: "session-id"

Automatic Session Save

The agent should automatically:

1. At the end of the session, save a summary of key decisions and context
2. At the start of a new session, search for relevant past context
3. Present relevant past context to the user naturally

Error Handling

Commands

/remember [text]     → Save an important piece of context
/search [query]      → Search past memory
/whatdidwe [topic]   → What did we discuss about X before?
/forget [id]         → Remove a specific memory entry

Anti-Patterns

Advanced ChromaDB Patterns

Collection Management

# List collections
collections = client.list_collections()
for c in collections: print(c.name, c.count())

# Create collection with custom embedding function
from chromadb.utils import embedding_functions
ef = embedding_functions.OpenAIEmbeddingFunction(api_key="...", model_name="text-embedding-3-small")
collection = client.create_collection(name="custom", embedding_function=ef)

# Delete by metadata filter
collection.delete(where={"project": "test-project"})

# Peek at stored data
sample = collection.peek(limit=5)

Embedding Model Selection

Default ONNX model (all-MiniLM-L6-v2) runs locally, no API key needed. Downloads once (~79MB).

Performance Tuning

# Batch inserts (100x faster than single inserts)
batch_size = 100
for i in range(0, len(documents), batch_size):
    collection.add(
        documents=documents[i:i+batch_size],
        metadatas=metadatas[i:i+batch_size],
        ids=ids[i:i+batch_size]
    )

# Limit query results
results = collection.query(query_texts=["query"], n_results=10)

# Get with limit (prevents OOM)
all_data = collection.get(limit=500, include=["documents", "metadatas"])

Storage Monitoring

import os

db_path = "~/.shokunin/memory/chroma_db"
size = sum(os.path.getsize(os.path.join(root, f)) for root, _, files in os.walk(db_path) for f in files)
print(f"Database size: {size / 1024 / 1024:.1f} MB")
print(f"Collection count: {collection.count()}")

Related Scripts

• ~/.shokunin/scripts/seed-memory.ps1 — Imports session markdown files into ChromaDB for first-time population
• ~/.shokunin/scripts/memory-healthcheck.ps1 — Verifies ChromaDB collection integrity and reports health status
• ~/.shokunin/scripts/read-transcript.py — Parses MCP session transcripts and extracts structured decisions and sections

Checklist

• Session ID is unique before storing (check with session list)
• Entry text is descriptive: what, why, and result (not just what)
• Type matches VALID_TYPES in MCP server config
• Tags align with previous entries for consistent search
• Session_end saved at end of every session

Sources

• ChromaDB documentation (docs.trychroma.com) — vector database setup, embedding models, and query best practices
• OpenAI text-embedding-ada-002 documentation (platform.openai.com/docs/guides/embeddings) — production embedding model benchmarks
• MCP Protocol specification (modelcontextprotocol.io) — agent-to-tool communication protocol
• Sentence Transformers all-MiniLM-L6-v2 (sbert.net/docs/pretrained_models.html) — lightweight local embedding alternative
• ONNX Runtime documentation (onnxruntime.ai) — cross-platform model inference for local embeddings
• "Designing Data-Intensive Applications" by Martin Kleppmann (O'Reilly, 2017) — durability, replication, and consistency patterns relevant to local DB design