OpenCode Memory

A standalone, harness-agnostic memory system for AI assistants.

Features

• PostgreSQL + pgvector - Robust, production-ready storage with vector search
• Event-sourced mutations - Every memory change is tracked
• Privacy-aware deletion - Delete/export operations redact event payloads
• Pluggable embeddings - Local (Ollama) or cloud (OpenAI) providers
• Hybrid retrieval - Full-text search + vector search + recency decay
• Secret detection - Automatically rejects content with credentials
• OpenCode integration - Thin adapter for seamless OpenCode use

Quick Start

1. Install

pip install -e .

2. Set up PostgreSQL

# Create database
createdb opencode_memory

# Run migrations
psql opencode_memory < sql/001_extensions.sql
psql opencode_memory < sql/002_core_schema.sql
psql opencode_memory < sql/003_indexes.sql
psql opencode_memory < sql/004_version_tracking.sql

3. Configure

export DATABASE_URL="postgresql://localhost:5432/opencode_memory"

# Optional: Configure Ollama for local embeddings
export OPENCODE_MEMORY_OLLAMA_URL="http://localhost:11434"

4. Use

CLI

# Create a session
opencode-memory create-session --session-id my-session --project-id my-project

# Record a turn
opencode-memory ingest-turn --session-id my-session --role user --content "Hello"

# Add a memory
opencode-memory add-memory --session-id my-session --type lesson --content "Use parameterized SQL"

# Search memories
opencode-memory retrieve --query "SQL queries" --session-id my-session

# Export memories
opencode-memory export --session-id my-session --output memories.json

# Delete memories
opencode-memory delete --session-id my-session

Python

from memory_core import MemoryStore, MemoryRetriever
from memory_core.embeddings import NullEmbeddingProvider

# Initialize
store = MemoryStore("postgresql://localhost:5432/opencode_memory")
retriever = MemoryRetriever("postgresql://localhost:5432/opencode_memory")

# Create session
session = store.create_session("my-session", project_id="my-project")

# Add memory
memory = store.add_memory(
    session_id="my-session",
    memory_type="lesson",
    content="Use parameterized SQL queries",
    importance=0.8
)

# Search memories
results = retriever.search_memories(
    query="SQL queries",
    session_id="my-session"
)

OpenCode Adapter

from adapters.opencode import OpenCodeMemoryAdapter

adapter = OpenCodeMemoryAdapter()

# Create session
adapter.create_session(session_id="my-session")

# Record turn
adapter.ingest_turn(session_id="my-session", role="user", content="Hello")

# Add memory explicitly
adapter.add_memory(
    session_id="my-session",
    memory_type="lesson",
    content="Use parameterized SQL"
)

# Get context for assistant
context = adapter.retrieve_context(
    query="SQL queries",
    session_id="my-session"
)

Architecture

Core Components

• memory_core/ - Standalone memory library

  • store.py - CRUD operations with event sourcing
  • retrieve.py - Hybrid retrieval engine
  • events.py - Privacy-aware event writer
  • security.py - Secret detection
  • export.py - Export/delete with redaction
  • summarize.py - Heuristic summarization

• adapters/ - Integration adapters

  • opencode.py - OpenCode integration

• sql/ - Database migrations

  • 001_extensions.sql - PostgreSQL extensions
  • 002_core_schema.sql - Table definitions
  • 003_indexes.sql - Performance indexes
  • 004_version_tracking.sql - Migration tracking

Design Principles

1. Harness-agnostic - No dependencies on specific AI harnesses
2. Local-first - Defaults to local embedding via Ollama
3. Event-sourced - Every mutation creates an audit event
4. Privacy-aware - Delete operations redact event payloads
5. Explicit memory writes - No automatic memory extraction

Embedding Providers

Null Provider (Default)

Disables vector operations. Use for testing or when you only need full-text search.

from memory_core.embeddings import NullEmbeddingProvider

store = MemoryStore(db_url, NullEmbeddingProvider())

Local Provider (Ollama)

Uses Ollama for local embeddings. Requires Ollama to be running.

from memory_core.embeddings import LocalEmbeddingProvider

provider = LocalEmbeddingProvider(model_name="nomic-embed-text")
store = MemoryStore(db_url, provider)

Cloud Providers (Opt-in)

Cloud providers require explicit API key configuration.

# OpenAI (not implemented yet, placeholder for future)
# from memory_core.embeddings import OpenAIEmbeddingProvider
# provider = OpenAIEmbeddingProvider(api_key="sk-...")

Testing

# Run tests
pytest

# Run with coverage
pytest --cov=memory_core --cov-report=html

Privacy

• Secret detection - Content with API keys, tokens, or passwords is rejected
• Event redaction - Delete/export operations redact event payloads
• No hidden copies - Deleted content is fully removed from all tables
• User control - Export and delete operations are always available

License

MIT