Hybrid-Memory MCP Usage Guide

Purpose: Quick reference for using hybrid-memory MCP tools in Axiom workflows
Status: ACTIVE
Version: 1.0.0
Last Updated: 2025-12-29

---

Overview

The hybrid-memory MCP provides semantic search across all Axiom workflow history, enabling agents to: - Find past decisions and patterns - Avoid repeating work - Learn from previous capabilities - Discover cross-capability insights

System: Hybrid RAG Memory v0.9.0-beta (keyword + semantic search with auto-indexing)

---

Available Tools

1. search_memory - Hybrid Search

Purpose: Search past conversations and workflow steps using keyword + semantic similarity

Parameters: - query (required): Search query string - limit (optional, default: 20): Max results - session_id (optional): Filter to specific session - mode (optional, default: "hybrid"): "hybrid", "keyword", or "semantic"

When to Use: - Before starting a phase - check for similar past work - When making decisions - search for precedents - During problem framing - find related problems - When generating solutions - find what worked before

Examples:

# Find executor interview patterns
search_memory("executor interviews technology adoption personas")

# Find RICE prioritization examples
search_memory("RICE scoring critical outcomes minimize time")

# Find capability thesis patterns
search_memory("capability thesis disagree and commit decision")

# Find specific problem types
search_memory("manual coordination overhead inefficiency")

Output Format:

Found 3 results for 'executor interviews':

Result 1 (Score: 0.892):
Session: session-20251215-143022
Timestamp: 2025-12-15T14:30:22Z
Role: assistant
Content: Conducted 6 executor interviews using Six Thinking Hats framework...

---

Result 2 (Score: 0.756):
...

---

2. get_memory_stats - Database Statistics

Purpose: View memory system health and usage statistics

Parameters: None

When to Use: - During status reporting (/status command) - During phase completion reports - When troubleshooting memory issues - During validation gates

Example:

get_memory_stats()

Output Format:

Memory Database Statistics:
- Total Sessions: 42
- Total Memory Entries: 1,247
- Entries with Embeddings: 1,180
- Database Size: 12.45 MB
- Schema Health: OK

---

3. list_sessions - Browse Sessions

Purpose: View recent conversation sessions with metadata

Parameters: - limit (optional, default: 20): Max sessions to return - offset (optional, default: 0): Pagination offset

When to Use: - Reviewing recent workflow history - Finding specific capability sessions - Understanding session patterns - Before starting similar work

Example:

# List 10 most recent sessions
list_sessions(limit=10)

# Pagination
list_sessions(limit=20, offset=20)  # Sessions 21-40

Output Format:

Found 10 sessions:

Session: session-20251229-093015 (ACTIVE)
Project: axiom
Started: 2025-12-29T09:30:15Z
Messages: 47
Duration: 1,235 seconds

---

Session: session-20251228-141522
Project: axiom
Started: 2025-12-28T14:15:22Z
Messages: 156
Duration: 3,847 seconds

---

4. get_session - View Session Details

Purpose: Retrieve complete session history with all messages

Parameters: - session_id (required): Session identifier

When to Use: - Reviewing specific capability workflows - Understanding decision context - Auditing workflow quality - Learning from completed work

Example:

get_session("session-20251228-141522")

Output Format:

Session: session-20251228-141522
Project: axiom
Started: 2025-12-28T14:15:22Z
Ended: 2025-12-28T18:20:15Z
Duration: 3,847 seconds
Message Count: 156

Messages:
---
Message 1:
Time: 2025-12-28T14:15:22Z
ID: entry-abc-123
Content: Starting Observe phase for device-lifecycle capability...

---
Message 2:
...

---

5. get_indexing_stats - Auto-Indexing Status

Purpose: Monitor background indexing queue and statistics

Parameters: None

When to Use: - Validating phase completion (ensure memories indexed) - Troubleshooting indexing issues - Monitoring system health - During validation gates

Example:

get_indexing_stats()

Output Format:

Auto-Indexing Statistics:

Queue Status:
- Total Enqueued: 127
- Pending: 2
- Completed: 123
- Failed: 2
- Success Rate: 98.4%

Middleware:
- Queries Captured: 127
- Capture Failures: 0

Background Worker:
- Processing Cycles: 45
- Last Run: 2025-12-29T10:15:32Z

---

Workflow Integration

During Phase Execution

@workflow-manager should use hybrid-memory at these points:

1. Phase Start

# Search for similar past work
search_memory("observe phase executor interviews")

2. After Each Step

# Auto-indexing happens automatically
# Step memories are captured by middleware

3. Phase Summary Creation

# Find cross-capability patterns
search_memory("orient phase problem statement RICE scoring")

# Verify indexing complete
stats = get_indexing_stats()
# Ensure pending = 0 before finalizing

4. Status Reporting

# Include memory stats
memory_stats = get_memory_stats()
indexing_stats = get_indexing_stats()

# Include in status report

---

Best Practices

1. Search Query Construction

Good Queries (specific, context-rich):

search_memory("executor interviews Six Thinking Hats technology adoption")
search_memory("RICE prioritization critical outcomes minimize coordination time")
search_memory("Blue Ocean strategy value innovation eliminate reduce")

Poor Queries (too generic):

search_memory("interviews")  # Too broad
search_memory("decision")    # Too vague
search_memory("step 1")      # Not semantic

2. Result Interpretation

• Score > 0.8: Highly relevant, strong match
• Score 0.6-0.8: Relevant, good context
• Score < 0.6: Tangentially related, review carefully

3. Indexing Validation

Before finalizing phases, ensure indexing complete:

stats = get_indexing_stats()
if stats["pending"] > 0:
    # Wait for indexing to complete
    # Or retry failed items

4. Cross-Capability Learning

Use search to find patterns across capabilities:

# Find recurring personas
search_memory("IT administrator operations team executor")

# Find common pain points
search_memory("manual coordination overhead inefficiency")

# Find successful frameworks
search_memory("JTBD outcomes minimize time risk cost")

---

Configuration

OpenCode Configuration

Location: .contributing/opencode.json

{
  "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
  }
}

Storage Locations

• Database: .memory/local.db
• Encryption Key: pass show axiom/hybrid-memory-encryption-key
• MCP Server: .roadmap/ready/implement-hybrid-rag-memory/hybrid-rag-memory-project/bin/hybrid-memory-server

---

Troubleshooting

Issue: "Search service not initialized"

Cause: MCP server not running or crashed

Solution:

# Check server status
ps aux | grep hybrid-memory-server

# Restart server (OpenCode handles this automatically)
# Or manually:
cd .roadmap/ready/implement-hybrid-rag-memory/hybrid-rag-memory-project
./bin/hybrid-memory-server

Issue: "No results found"

Cause: Query too specific or no relevant indexed content

Solution: - Broaden query terms - Check indexing status: get_indexing_stats() - Verify database has content: get_memory_stats()

Issue: "Pending indexing items"

Cause: Background worker still processing

Solution: - Wait 5-10 seconds (worker runs every 5s) - Check again: get_indexing_stats() - If stuck, check worker logs in stderr

---

Related Documentation

• MEMORY-PROTOCOL.md - Memory management rules
• AGENTS.md - Agent navigation
• Hybrid-Memory README - MCP server documentation

---

Version: 1.0.0
Status: ACTIVE