Skip to content

Memory Management Protocol

Purpose: Rules and standards for step-level and phase-level memory creation, compression, and access
Status: ACTIVE
Version: 2.0.0
Last Updated: 2025-12-29

🧠 Hybrid Memory System

Axiom uses a dual-layer memory architecture:

  1. File-based Memory - Markdown files for human-readable workflow history
  2. Hybrid RAG Memory - MCP-based semantic search across all conversations (v0.9.0-beta)

Available Hybrid-Memory MCP Tools

The following tools are available via the hybrid-memory MCP server (configured in .contributing/opencode.json):

Tool Purpose Usage
search_memory Hybrid search (keyword + semantic) Find past decisions, patterns, insights
get_memory_stats Database statistics Monitor memory usage and health
list_sessions Browse conversation sessions View recent workflows and sessions
get_session View session details Retrieve complete session history
get_indexing_stats Auto-indexing statistics Monitor background indexing queue

Auto-Indexing: All search queries and workflow steps are automatically indexed into the hybrid memory system for future semantic search.

When to Use Hybrid-Memory Tools

@workflow-manager and all agents SHOULD use hybrid-memory tools when:

  • Searching for past decisions: Use search_memory to find similar problems/solutions from previous capabilities
  • Cross-capability insights: Search across all OODA phases and capabilities for patterns
  • Status reporting: Use get_memory_stats to include memory metrics in status reports
  • Session review: Use list_sessions and get_session to review recent workflow history
  • Avoiding repetition: Before making decisions, search memory to leverage past learnings

Example Queries: 

search_memory("executor interview personas technology adoption")
search_memory("RICE prioritization critical outcomes")
search_memory("capability thesis disagree and commit")

🔄 File-Based Memory Hierarchy

.roadmap/<stage>/<capability>/
├── observe/
│   ├── memory/
│   │   ├── step-1.md                # Step 1 memory (100-200 tokens)
│   │   ├── step-2.md                # Step 2 memory
│   │   ├── ...
│   │   ├── step-8.md                # Step 8 memory
│   │   └── observe-phase-summary.md # Phase summary (850 tokens, 18.5x compression)
│   └── artifacts/
│       └── (job-definition.md, etc.)
├── orient/
│   ├── memory/
│   │   ├── step-1.md                # Step 1 memory
│   │   ├── ...
│   │   ├── step-9.md                # Step 9 memory
│   │   └── orient-phase-summary.md  # Phase summary (700 tokens, 9.8x compression)
│   └── artifacts/
│       └── (problem-statement.md, etc.)
├── recommend/
│   ├── memory/
│   │   ├── step-1.md                # Step 1 memory
│   │   ├── ...
│   │   ├── step-8.md                # Step 8 memory
│   │   └── recommend-phase-summary.md # Phase summary (800 tokens, 10.9x compression)
│   └── artifacts/
│       └── (recommendation.md, etc.)
├── align/
│   ├── memory/
│   │   ├── step-1.md                # Step 1 memory
│   │   ├── step-2.md                # Step 2 memory
│   │   ├── step-3.md                # Step 3 memory
│   │   ├── step-4.md                # Step 4 memory
│   │   └── align-phase-summary.md   # Phase summary (900 tokens, 14.1x compression)
│   └── artifacts/
│       └── (capability-thesis.md, etc.)
└── workflow-summary.md              # Full workflow summary (3,000 tokens)

📝 Step-Level Memory Protocol (MANDATORY)

After EVERY workflow step, @workflow-manager MUST create a step memory file.

Step Memory Requirements

File Location: <phase>/memory/step-<number>.md
File Naming: EXACT pattern - step-1.md, step-2.md, etc. - ❌ WRONG: step-3-4.md, recommend-step-1.md, orient-step-7.md - ✅ CORRECT: step-3.md, step-4.md (separate files)

Content Structure (100-200 tokens per step): 

# Step <N> Memory: <Step Title>

## Actions Taken
- <Key action 1>
- <Key action 2>

## Artifacts Created
- <artifact-name.md> - <brief purpose>

## Key Decisions
- <Decision 1>
- <Decision 2>

## Validation Status
- ✅/<❌> <Validation result>

## Next Step Context
<1-sentence handoff to next step>

Expected Step Memory Counts by Phase

  • Observe: 8 step memories (step-1.md through step-8.md)
  • Orient: 9 step memories (step-1.md through step-9.md)
  • Recommend: 8 step memories (step-1.md through step-8.md)
  • Align: 4 step memories (step-1.md through step-4.md)

Total Expected: 29 step memory files across all phases

🔍 Memory Access Rules

Sequential Phase Reading

  • Orient reads observe/memory/observe-phase-summary.md (not individual step memories)
  • Recommend reads orient/memory/orient-phase-summary.md (not individual step memories)
  • Align reads recommend/memory/recommend-phase-summary.md (not individual step memories)

Cross-Phase Reading (Special Cases)

  • @senior-product-manager reads ALL phase summaries for capability thesis
  • @quality-assurance reads ALL phase summaries + step memories for validation
  • @workflow-manager reads ALL phase summaries for status reports
  • /status command reads ALL phase summaries for progress report

📊 Phase Summary Creation (After Each Phase)

Agent: @workflow-manager
Timing: After all step memories created, before phase finalization
Target Compression: 15-20x (e.g., 15,000 tokens → 850 tokens)

Content: Key decisions + Metrics + Validation results only (NO step-by-step narrative)
Template: .contributing/templates/phase-memory.md.template

Hybrid-Memory Integration

After creating phase summary, @workflow-manager SHOULD:

  1. Index phase summary - The phase summary is automatically indexed via background worker
  2. Search for related insights - Use search_memory to find patterns from past phases
  3. Include cross-capability learnings - Reference relevant decisions from other capabilities
  4. Update memory stats - Include get_memory_stats output in phase completion report

Example: 

## Phase Completion Report

### Memory Statistics
[Output from get_memory_stats]

### Related Insights
[Results from search_memory for similar phase/problem]

### Cross-Capability Patterns
- Found 3 similar executor personas in capability "device-lifecycle-optimization"
- Consistent pattern: Manual coordination overhead (avg 16 hrs/week)

🔄 Memory Update Protocol (When Artifacts Change)

Agent: @workflow-manager
Trigger: Any artifact modification after phase completion

Actions: 1. Update affected step memory (if step-level change) 2. Update phase summary (if phase-level impact) 3. Increment version number in memory metadata 4. Document change rationale in memory file

✅ Validation Requirements

Before Phase Finalization: 1. ✅ All step memories present (count matches expected: 8/9/8/4) 2. ✅ Phase summary created 3. ✅ All step memories follow naming convention (step-N.md) 4. ✅ Phase summary location correct (<phase>/memory/<phase>-phase-summary.md) 5. ✅ Hybrid-memory MCP server running and accessible 6. ✅ Phase summary indexed in hybrid-memory (verify with get_indexing_stats)

Phase CANNOT finalize if any validation fails.

🔧 Hybrid-Memory Configuration

MCP Server Setup

The hybrid-memory MCP server is configured in .contributing/opencode.json:

{
  "mcp": {
    "hybrid-memory": {
      "type": "local",
      "command": [".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
    }
  }
}

Storage Location

  • Database: .memory/local.db (SQLite with FTS5 for keyword search)
  • Encryption Key: Stored in pass (Unix password manager) at axiom/hybrid-memory-encryption-key
  • Session Data: Auto-indexed search queries and workflow steps

Prerequisites

  1. Poetry - Python dependency manager
  2. pass - Unix password manager for encryption keys
  3. macOS: brew install pass
  4. Linux: apt install pass or yum install pass
  5. GPG - Required by pass for key encryption
  6. Generate key: gpg --full-generate-key
  7. Ollama - For semantic embeddings (optional, falls back to keyword-only)

Verification

Check hybrid-memory is working:

# Check MCP server status
curl http://localhost:8000/health

# View memory statistics
# Use get_memory_stats tool in OpenCode

# Test search
# Use search_memory tool in OpenCode

Related Documentation: - AGENTS.md - Main agent navigation - PROCESS-STANDARDS.md - Artifact requirements - VALIDATION-GATES.md - Phase transition gates - HYBRID-MEMORY-USAGE.md - Hybrid-memory MCP tools guide (NEW)

Referenced By: - .contributing/agent/workflow-manager.md - Primary memory manager - .contributing/agent/memory-auditor.md - Memory validation agent - All workflow phase agents

Hybrid-Memory MCP: - Hybrid-Memory README - MCP server documentation - .contributing/opencode.json - MCP configuration