Skip to content

EliasOulkadi/shokunin / .pack/skills/memory

memory

Verified

Persistent memory across AI sessions using ChromaDB vector database. Stores and retrieves context from past conversations, decisions, and code. Use when user asks to remember something, search past conversations, recall what was done before, save context for later, or find information from previous sessions. Do NOT use for git history or file-based notes.

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

ErrorCauseFix
ChromaDB not foundNot installedpip install chromadb
Collection not foundFirst runCreates automatically on first store
Slow first queryDownloading ONNX modelFirst run downloads ~79MB. Subsequent runs are instant.
Memory not returning resultsNo data stored yetNormal on first use. Start by saving something.
Embedding model fails to downloadNetwork blocked or proxy requiredSet CHROMADB_EMBEDDING_MODEL env var. Fall back to all-MiniLM-L6-v2 which is smaller (~23MB).
Duplicate or stale entries flooding resultsAuto-save firing too frequently during rapid iterationApply 5-second debounce before storing context. Consolidate entries with memory_consolidate_memories periodically.
Collection corrupted after crashWrite interrupted during power loss or force-quitRestore from latest backup in ~/.shokunin/memory/backups/. Run memory-healthcheck.ps1 to verify integrity.
Search returns irrelevant results for short queriesUnder-2-word queries have poor vector signalUse 3+ word queries. Include project name, topic, and a descriptive verb phrase.
Session ID collision or reuseWrapper failed to generate unique ID, or manual copy-pasteCheck ~/.shokunin/current-session.json. Run python chroma-helper.py session list to verify uniqueness.

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

PatternProblemFix
Storing secrets or tokens in memory entriesPlaintext memory is readable by any process with filesystem accessNever store API keys, passwords, or tokens. Use environment variables or a dedicated secret manager.
Saving every single message instead of checkpointsFloods the vector DB with near-duplicate embeddings, degrading search qualitySave only decisions, file changes, and commands. Debounce rapid successive saves to 5 seconds.
Using memory as a key-value storeChromaDB is optimized for semantic similarity, not exact-match lookupsUse the file system or a config file for deterministic data. Reserve memory for fuzzy, contextual recall.
Searching with overly broad queries like "what did we do"Returns too many low-relevance results, wasting tokens and attentionNarrow the query: project name + topic + timeframe. Example: "auth refactoring decisions May 2026".
Not consolidating old sessionsVector DB grows unbounded, slowing queries and increasing disk usageRun memory_consolidate_memories weekly. Archive sessions older than 90 days.
Assuming memory entries are immutable truthEntries represent frozen-in-time claims. Code may have changed since then.Always verify file paths and function names before acting. Use verify_file_path or grep to confirm.
Skipping session search at conversation startLoses all context from prior work, forcing the agent to re-discover already-solved problemsMandatory step: always run session list and search before responding to any task.

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

ModelDimensionsSpeedAccuracy
all-MiniLM-L6-v2 (default/ONNX)384FastestGood for short text
text-embedding-3-small (OpenAI)1536API-dependentExcellent
text-embedding-3-large (OpenAI)3072API-dependentBest (expensive)

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
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall