Hybrid-Memory MCP Integration Summary¶

Date: 2025-12-29
Status: COMPLETE
Version: Memory Protocol v2.0.0

Overview¶

Axiom's memory protocol now leverages the Hybrid RAG Memory MCP (v0.9.0-beta) for semantic search across all workflow history, enabling agents to:

✅ Search past decisions and patterns across capabilities
✅ Avoid repeating work through cross-capability learning
✅ Discover insights from previous OODA workflows
✅ Auto-index all workflow steps for future retrieval

Changes Made¶

1. OpenCode Configuration (`.contributing/opencode.json`)¶

Updated MCP configuration:

{
  "mcp": {
    "hybrid-memory": {
      "type": "local",
      "command": [
        "/Users/cavellebenjamin/Developer/axiom/.roadmap/ready/implement-hybrid-rag-memory/hybrid-rag-memory-project/bin/hybrid-memory-server"
      ],
      "enabled": true,
      "environment": {
        "HYBRID_MEMORY_DIR": "/Users/cavellebenjamin/Developer/axiom/.memory",
        "HYBRID_MEMORY_PASS_NAME": "axiom/hybrid-memory-encryption-key"
      },
      "timeout": 10000
    }
  },
  "tools": {
    "hybrid-memory*": true
  }
}

Changes: - ✅ Uses binary wrapper (bin/hybrid-memory-server) instead of poetry commands - ✅ Configures database location to .memory/local.db - ✅ Uses pass (Unix password manager) for encryption key storage - ✅ Increased timeout to 10 seconds for startup - ✅ Enables all hybrid-memory tools globally

2. Memory Protocol Documentation (`docs/MEMORY-PROTOCOL.md`)¶

Version: 1.0.0 → 2.0.0

New Sections: - 🧠 Hybrid Memory System - Overview of dual-layer architecture - 📊 Available MCP Tools - Table of 5 hybrid-memory tools - 🔧 Hybrid-Memory Configuration - Setup and prerequisites - ✅ Updated Validation - Added hybrid-memory indexing verification

Key Additions: - When to use hybrid-memory tools (search, stats, sessions) - Integration with phase summary creation - Cross-capability insights in phase summaries - Memory indexing validation requirements

3. Workflow Manager Agent (`.contributing/agent/workflow-manager.md`)¶

New Responsibilities: - Use search_memory before starting phases - Find cross-capability patterns during phase summaries - Include memory stats in status reports - Verify auto-indexing with get_indexing_stats()

Updated Process: - Step 2 (new): Search hybrid-memory for related insights - Step 6 (new): Add cross-capability learnings section - Step 8 (new): Verify auto-indexing complete

4. Phase Memory Template (`.contributing/templates/phase-memory.md.template`)¶

New Section: Cross-Capability Insights

## Cross-Capability Insights

**Search Query**: `search_memory("[key themes from this phase]")`

### Related Patterns
- [Pattern 1 from past capabilities]

### Reusable Decisions
- [Decision from past work that informed this phase]

### Avoided Pitfalls
- [Known issue avoided based on past experience]

Updated Validation: - Added "Memory Indexed" status check - Added hybrid_memory_indexed and search_queries_used to metadata

5. New Usage Guide (`docs/HYBRID-MEMORY-USAGE.md`)¶

Purpose: Quick reference for agents using hybrid-memory tools

Contents: - Tool descriptions with parameters and examples - Workflow integration points - Best practices for search queries - Troubleshooting guide - Configuration reference

Key Tools Documented: 1. search_memory - Hybrid search (keyword + semantic) 2. get_memory_stats - Database statistics 3. list_sessions - Browse sessions 4. get_session - View session details 5. get_indexing_stats - Auto-indexing status

Architecture¶

Dual-Layer Memory System¶

Layer 1: File-Based Memory (Human-readable)

.roadmap/<stage>/<capability>/
├── observe/memory/
│   ├── step-1.md
│   └── observe-phase-summary.md
└── workflow-summary.md

Layer 2: Hybrid RAG Memory (Semantic search)

.memory/
└── local.db (SQLite + FTS5 + embeddings)

Auto-Indexing Flow¶

Workflow Step → Auto-capture → Indexing Queue → Background Worker → Database
                    ↓              ↓                    ↓              ↓
                 Instant       SQLite FIFO      Process every 5s   Searchable

Tool Usage by Phase¶

OBSERVE Phase¶

# Before starting
search_memory("executor interviews JTBD personas")

# During phase summary
search_memory("observe phase outcomes minimize time risk")
get_indexing_stats()  # Verify indexing complete

ORIENT Phase¶

# Before starting
search_memory("problem statement medical model RICE scoring")

# During phase summary
search_memory("orient phase critical problems prioritization")
get_memory_stats()  # Include in status report

# Before starting
search_memory("solution hypotheses SCAMPER Blue Ocean")

# During phase summary
search_memory("recommend phase Toulmin argument value innovation")
list_sessions(limit=10)  # Review recent similar work

ALIGN Phase¶

# Before starting
search_memory("capability thesis disagree commit execution plan")

# During capability thesis
search_memory("all OODA phases")  # Cross-phase insights
get_session("session-id")  # Review entire workflow

Benefits¶

1. Cross-Capability Learning¶

Agents can search all past capabilities for similar problems
Avoid repeating past mistakes
Reuse successful frameworks and patterns

2. Institutional Memory¶

Nothing is forgotten - all decisions searchable
New agents can learn from past work
Continuous improvement through pattern recognition

3. Faster Decision Making¶

Search for precedents before deciding
Find proven solutions faster
Build on past work instead of starting fresh

4. Quality Improvement¶

Learn what worked/didn't work in past
Identify recurring pain points
Refine frameworks based on usage patterns

Validation¶

Before Phase Finalization¶

File-based memory (existing): 1. ✅ All step memories present 2. ✅ Phase summary created 3. ✅ Naming conventions followed

Hybrid-memory (new): 4. ✅ MCP server running and accessible 5. ✅ Phase summary indexed (get_indexing_stats()) 6. ✅ Cross-capability insights included in phase summary

Prerequisites¶

System Requirements¶

Poetry - Python dependency manager

curl -sSL https://install.python-poetry.org | python3 -

pass - Unix password manager

# macOS
brew install pass

# Linux
apt install pass  # or yum install pass

GPG - For pass encryption
```
gpg --full-generate-key
```
Ollama - For semantic embeddings (optional)
```
# Download from https://ollama.ai/
```

First-Time Setup¶

The binary wrapper (bin/hybrid-memory-server) handles initialization automatically:

Creates .memory/ directory
Initializes SQLite database
Generates encryption key in pass store
Starts MCP server

No manual setup required - just restart OpenCode!

Testing¶

Verify MCP Server¶

# Check server is running
ps aux | grep hybrid-memory-server

# Check database exists
ls -la .memory/local.db

# Check encryption key
pass show axiom/hybrid-memory-encryption-key

Test Tools in OpenCode¶

# Test search
search_memory("test query")

# Test stats
get_memory_stats()

# Test sessions
list_sessions(limit=5)

# Test indexing
get_indexing_stats()

Migration Path¶

Existing Capabilities¶

Retroactive indexing (optional): 1. Read existing phase summaries and step memories 2. Index into hybrid-memory manually (future enhancement) 3. For now, new workflows auto-index starting now

Future Enhancements¶

Bulk import - Script to index all existing capabilities
Session-scoped search - Search within specific capability
Temporal filtering - Search by date range
Tag-based search - Search by phase, agent, framework

Troubleshooting¶

Issue: MCP server won't start¶

Check prerequisites:

which poetry  # Should show path
which pass    # Should show path
gpg --list-secret-keys  # Should show GPG key

Initialize pass (if needed):

gpg --full-generate-key
pass init <your-gpg-key-id>

Issue: "Search service not initialized"¶

Restart OpenCode - MCP server starts automatically

Issue: No search results¶

Check indexing status:

get_indexing_stats()

Wait for pending items to complete (5-10 seconds)

MEMORY-PROTOCOL.md - Memory management rules (v2.0.0)
HYBRID-MEMORY-USAGE.md - Tool usage guide
Hybrid-Memory README - MCP server docs

Next Steps¶

Restart OpenCode - To load new MCP configuration
Test tools - Verify all 5 tools work
Run next workflow - Auto-indexing starts immediately
Review results - Check cross-capability insights in phase summaries

Version: 1.0.0
Status: COMPLETE
Integration Date: 2025-12-29