git clone https://github.com/marc-shade/enhanced-memory-mcp.git
cd enhanced-memory-mcp
uv venv --python 3.11 .venv
source .venv/bin/activate
uv pip install -r requirements.txt

{
  "mcpServers": {
    "enhanced-memory": {
      "command": "python3",
      "args": ["/path/to/enhanced-memory-mcp/server.py"]
    }
  }
}

{
  "mcpServers": {
    "enhanced-memory": {
      "command": "/path/to/enhanced-memory-mcp/.venv/bin/python3",
      "args": ["/path/to/enhanced-memory-mcp/server.py"]
    }
  }
}

server.py                    # Main FastMCP entry point
├── server/                  # Core server modules
│   ├── config.py            # Configuration and logging
│   ├── database.py          # SQLite connection management
│   ├── compression.py       # zlib compression engine
│   ├── compaction.py        # Entity compaction and cleanup
│   ├── integrity.py         # SHA256 integrity verification
│   ├── versioning.py        # Git-like memory versioning
│   └── modules.py           # Profile-based module loader
├── router/                  # Intelligent LLM routing
│   ├── router.py            # Multi-provider router
│   ├── intelligent_router.py # Uncertainty-aware routing
│   ├── uncertainty.py       # Uncertainty scoring
│   └── providers/           # Provider implementations
├── sandbox/                 # Code execution sandbox
│   ├── executor.py          # RestrictedPython execution
│   ├── security.py          # Safety checks
│   ├── pii_tokenizer.py     # PII detection and tokenization
│   ├── lazy_loader.py       # Deferred module loading
│   └── tool_discovery.py    # Dynamic tool discovery
├── agi/                     # AGI cognitive modules (22 files)
│   ├── consolidation.py     # Sleep-like memory consolidation
│   ├── metacognition.py     # Self-awareness tracking
│   ├── belief_tracking.py   # Probabilistic belief states
│   ├── temporal_reasoning.py # Causal chains
│   ├── emotional_memory.py  # Emotional tagging
│   └── ...
├── *_tools.py (31 files)    # MCP tool modules
└── test_*.py (67 files)     # Test suite

# Full mode (default): All 200+ tools loaded
MEMORY_PROFILE=full python3 server.py

# Orchestrator mode: ~15 essential tools for coordination
MEMORY_PROFILE=orchestrator python3 server.py

-- Core memory storage with compression and versioning
CREATE TABLE entities (
    id INTEGER PRIMARY KEY,
    name TEXT UNIQUE NOT NULL,
    entity_type TEXT NOT NULL,
    tier TEXT DEFAULT 'working',
    compressed_data BLOB,
    original_size INTEGER,
    compressed_size INTEGER,
    compression_ratio REAL,
    checksum TEXT,
    created_at TIMESTAMP,
    accessed_at TIMESTAMP,
    access_count INTEGER DEFAULT 0
);

-- Entity relationships with causal tracking
CREATE TABLE relations (
    id INTEGER PRIMARY KEY,
    from_entity TEXT NOT NULL,
    to_entity TEXT NOT NULL,
    relation_type TEXT NOT NULL,
    weight REAL DEFAULT 1.0,
    causal INTEGER DEFAULT 0,
    created_at TIMESTAMP,
    UNIQUE(from_entity, to_entity, relation_type)
);

-- Git-like version history
CREATE TABLE entity_versions (
    id INTEGER PRIMARY KEY,
    entity_name TEXT NOT NULL,
    version INTEGER NOT NULL,
    branch TEXT DEFAULT 'main',
    compressed_data BLOB,
    checksum TEXT,
    created_at TIMESTAMP
);

await create_entities({
    "entities": [
        {
            "name": "project_alpha",
            "entityType": "project",
            "observations": ["Architecture uses microservices", "Deployed on Kubernetes"]
        }
    ]
})

await search_nodes({
    "query": "microservices architecture",
    "entity_types": ["project"],
    "limit": 10
})

await unified_search({
    "query": "How does authentication work?",
    "strategy": "auto"  # Automatically selects best RAG strategy
})

await agentic_retrieve({
    "query": "memory consolidation patterns",
    "max_iterations": 3,
    "quality_threshold": 0.7
})

# Open a memory block for editing
await nmf_open_block({"block_id": "working_context"})

# Edit the block
await nmf_edit_block({
    "block_id": "working_context",
    "content": "Current focus: implementing authentication module"
})

# Recall related memories
await nmf_recall({"query": "authentication patterns"})

# Close the block
await nmf_close_block({"block_id": "working_context"})

# Cache an LLM reasoning result
await semantic_cache_store({
    "query": "Explain transformer attention mechanisms",
    "result": "Transformers use self-attention to...",
    "ttl_hours": 24
})

# Retrieve cached result (fuzzy match)
await semantic_cache_get({
    "query": "How do transformer attention heads work?"
})

# Create a branch
await memory_branch({"branch_name": "experiment-v2"})

# Make changes, then diff
await memory_diff({"branch": "experiment-v2", "base": "main"})

# Revert if needed
await memory_revert({"entity_name": "project_alpha", "version": 3})

# Run comprehensive test suite
python3 comprehensive_test.py

# RAG integration tests (22 tests)
python3 test_rag_integration_comprehensive.py

# Test specific subsystems
python3 test_graphrag_integration.py
python3 test_manifold_working_memory.py
python3 test_triple_signal_search.py
python3 test_surprise_consolidation.py
python3 test_trajectory_compression.py
python3 test_anti_hallucination.py
python3 test_causal_inference.py

# AGI phase tests
python3 test_agi_phase1.py
python3 test_agi_phase2.py
python3 test_agi_phase3.py
python3 test_agi_phase4.py

# Code execution sandbox
python3 test_advanced_tool_use.py

def register_{feature}_tools(app, *args):
    @app.tool()
    async def my_new_tool(param: str) -> str:
        """Tool description shown in MCP."""
        return result

if should_load_module("{feature}_tools"):
    try:
        from {feature}_tools import register_{feature}_tools
        register_{feature}_tools(app)
    except Exception as e:
        logger.warning(f"{feature} integration skipped: {e}")