Related Pages

Related topics: System Architecture, Quick Start Guide, MCP Server & Tools

Overview

MIND-Mem is a multi-agent memory and knowledge management system designed to provide persistent, queryable memory for AI coding assistants. It maintains a structured workspace containing decisions, tasks, entities, signals, and contradictions—enabling AI agents to recall relevant context across sessions while enforcing governance rules that prevent unauthorized memory modifications.

Purpose and Scope

MIND-Mem solves the context window exhaustion problem in long-running AI-assisted development by:

• Storing structured memories in markdown files organized by type (DECISIONS.md, TASKS.md, entities, signals)
• Providing fast retrieval via BM25 full-text search and FTS5 SQLite indexes
• Enforcing governance through a propose → approve → apply workflow
• Maintaining audit trails with SHA3-512 hash chains and Merkle proofs
• Supporting compiled truth pages that aggregate evidence for key entities

Sources: src/mind_mem/compiled_truth.py:1-30

Architecture Overview

The system consists of several interconnected layers:

graph TD
    subgraph "Client Layer"
        CLI[CLI mm]
        MCP[MCP Server]
        WEB[Web Console]
    end
    
    subgraph "Core Engine"
        RECALL[Recall Engine]
        IDX[FTS5 Index]
        GOV[Governance]
        AUDIT[Audit Chain]
    end
    
    subgraph "Storage Layer"
        MARKDOWN[Markdown Files]
        SQLITE[SQLite DB]
        KERNEL[.mind Kernel Configs]
    end
    
    CLI --> MCP
    WEB --> RECALL
    RECALL --> IDX
    RECALL --> MARKDOWN
    GOV --> MARKDOWN
    AUDIT --> IDX
    KERNEL --> RECALL

Sources: src/mind_mem/mm_cli.py:1-25

Workspace Structure

Each workspace managed by MIND-Mem follows a canonical directory layout:

Sources: src/mind_mem/compiled_truth.py:80-100

MCP Server Surface

The MCP (Model Context Protocol) server exposes a comprehensive tool surface organized into domains:

Core Tool Domains

Sources: src/mind_mem/mcp/tools/governance.py:1-30

MCP Resources

The server also exposes read-only resources via the MCP resource protocol:

Sources: src/mind_mem/mcp/resources.py:1-40

CLI Interface

The mm command provides a unified interface for non-MCP agents:

mm recall "<query>"             # Search memory with BM25
mm context "<query>"           # Generate token-budgeted snippet
mm inject --agent <name> "<q>" # Render snippet for specific agent
mm vault scan <vault_root>      # List parsed vault blocks (JSON)
mm vault write <vault_root> <id> --type <t> --body <b>
mm status                       # Workspace summary

Sources: src/mind_mem/mm_cli.py:30-55

Governance Model

MIND-Mem enforces an invariant: memory is never modified except by governance. The governance workflow:

graph LR
    A[Propose] --> B{Human Review}
    B -->|Approved| C[Apply/Dry-Run]
    B -->|Rejected| D[Discard]
    C -->|Dry-Run| E[Review Changes]
    E -->|Confirm| F[Commit]
    F --> G[Snapshot Stored]
    C -->|Direct| F
    G --> H[Rollback Available]

Key governance tools:

• propose_update — Stage a new decision/task as a SIGNAL
• approve_apply — Apply a staged proposal (dry-run by default)
• rollback_proposal — Restore workspace from pre-apply snapshot

Sources: src/mind_mem/mcp/tools/governance.py:35-60

Compiled Truth System

Compiled truth pages aggregate evidence for key entities, enabling efficient retrieval of canonical understanding:

graph TD
    A[Memory Files] --> B[Sentence Extraction]
    B --> C[Fact Candidates]
    C --> D{min_mentions?}
    D -->|≥3| E[Promote to Truth]
    E --> F[Compiled Section]
    G[New Evidence] --> H[Add Entry]
    H --> I[Recompile]
    I --> F

The system supports:

• Evidence entries with timestamps, sources, and confidence levels
• Superseding outdated evidence
• Version tracking with recompilation

Sources: src/mind_mem/compiled_truth.py:150-200

Integrity and Audit

MIND-Mem provides cryptographic integrity guarantees:

Protection Module

The protection system validates critical module integrity:

• Critical modules include recall, vector search, apply engine, audit chain, encryption, graph recall, rerank ensemble, consensus vote, tenant audit, and governance
• Integrity manifest (_integrity_manifest.json) stores SHA-256 hashes
• Strict mode available via MIND_MEM_INTEGRITY environment variable

Sources: src/mind_mem/protection.py:35-60

Audit Chain

Sources: src/mind_mem/mcp/tools/audit.py:1-30

Agent Integration

MIND-Mem supports integration with various AI coding assistants through a declarative registry:

The hook installer resolves the MCP server path through:

1. MIND_MEM_MCP_SERVER environment variable (explicit override)
2. <package_dir>/../mcp_server.py (src-layout checkout)
3. <package_dir>/mcp_server.py (packaged install)

Sources: src/mind_mem/hook_installer.py:20-45

v4.0 Surface

The v4.0 implementation is gated by feature flags in mind-mem.json under the v4 key:

Without the feature flag, v3.x behavior is preserved unchanged.

Sources: src/mind_mem/v4/__init__.py:1-40

Web Console

A Next.js web interface provides visual exploration:

graph LR
    A[API /v1/recall] --> B[Bundle Response]
    B --> C[GraphView]
    B --> D[TimelineView]
    B --> E[FactList]
    C --> F[d3-force graph]
    D --> G[Chronological events]
    E --> H[Extracted claims]

Components:

• app/page.tsx — Single-page console
• components/GraphView.tsx — Force-directed block graph
• components/TimelineView.tsx — Dated events timeline
• components/FactList.tsx — Extracted facts with confidence

Sources: web/README.md:1-30

Configuration

Workspace Resolution

The workspace is resolved in order:

1. MIND_MEM_WORKSPACE environment variable
2. Current working directory (cwd)

def _workspace() -> str:
    ws = os.environ.get("MIND_MEM_WORKSPACE", "").strip()
    if not ws:
        ws = os.getcwd()
    return os.path.realpath(ws)

MCP Server Invocation

The canonical MCP server invocation record:

{
    "command": "python3",
    "args": ["mcp_server.py"],
    "env": {"MIND_MEM_WORKSPACE": workspace}
}

Sources: src/mind_mem/hook_installer.py:50-70

Quick Start

# Install
pip install -e .

# Initialize workspace
mm status

# Search memory
mm recall "authentication"

# Context for agent
mm context "database schema"

# Web interface
cd web && pnpm install && pnpm dev

Sources: examples/README.md:1-20

Summary

MIND-Mem provides a robust multi-agent memory system with:

• Structured storage for decisions, tasks, entities, and signals
• Fast retrieval via BM25 and FTS5 indexes
• Governance-first memory modification workflow
• Cryptographic integrity through Merkle proofs and hash chains
• Extensive tooling via CLI, MCP server, and web console
• Agent integration support for Claude, Cursor, Codex, and more

Related Pages

Related topics: Overview, Block Format & Data Model, Governance & Safety

Key Concepts

Mind-Mem is a persistent memory system designed for multi-agent workflows. It stores structured knowledge as markdown "blocks" that can be recalled, reasoned about, and governed by a set of declarative rules. Understanding the core data model and access control mechanisms is essential for effective use.

Related Pages

Related topics: Overview, MCP Server & Tools

Quick Start Guide

Overview

The Quick Start Guide provides a comprehensive introduction to mind-mem, a persistent memory system designed for AI coding assistants. Mind-mem enables multi-agent teams to store, recall, and govern structured memory blocks across development sessions.

Purpose and Scope

Mind-mem serves as a unified memory layer that:

• Parses and indexes markdown-based memory blocks (DECISIONS, TASKS, SIGNALS, etc.)
• Provides BM25 and vector-based recall capabilities
• Supports MCP (Model Context Protocol) integration for AI assistants
• Implements governance workflows for memory evolution
• Offers a CLI (mm) for direct workspace interaction

This guide walks through installation, workspace initialization, basic operations, and first steps for integrating mind-mem into your development workflow.

Sources: examples/README.md:1-15

Architecture Overview

graph TD
    subgraph "Client Layer"
        CLI["mm CLI"]
        MCP["MCP Server"]
        WEB["Web Console"]
    end
    
    subgraph "Core Modules"
        RECALL["recall.py<br/>BM25 + Vector Recall"]
        COGNITIVE["cognitive_forget.py<br/>Token Budget Packing"]
        PARSER["block_parser.py<br/>Markdown Parsing"]
    end
    
    subgraph "Storage Layer"
        FTS["FTS Index<br/>SQLite FTS5"]
        META["Block Metadata"]
    end
    
    CLI --> RECALL
    MCP --> RECALL
    WEB --> RECALL
    RECALL --> PARSER
    RECALL --> FTS
    PARSER --> META

The system follows a layered architecture where the CLI and MCP server expose recall and governance APIs, while the core modules handle parsing, indexing, and retrieval.

Sources: src/mind_mem/mm_cli.py:1-25

Prerequisites

Before getting started with mind-mem, ensure your environment meets these requirements:

For full feature support including encryption and governance:

• OpenSSL 1.1.1+ (for encryption features)
• watchgod or watchdog (optional, for file watching)

Sources: examples/README.md:1-20

Installation

Standard Installation

Install mind-mem from the repository in development/editable mode:

pip install -e .

This installs the package with all dependencies and makes the mm CLI available system-wide.

Sources: examples/README.md:12-15

Package Structure

After installation, the following components become available:

Workspace Environment

Mind-mem resolves the workspace directory using this precedence:

graph LR
    A["MIND_MEM_WORKSPACE<br/>Environment Variable"] --> B{Set?}
    B -->|Yes| C["Use env value"]
    B -->|No| D["Current Working<br/>Directory"]
    C --> E["Realpath Resolution"]
    D --> E

Set the workspace explicitly:

export MIND_MEM_WORKSPACE=/path/to/your/project

Sources: src/mind_mem/mm_cli.py:35-50

Basic Usage

Running the First Example

The basic_usage.py example demonstrates core functionality:

python3 examples/basic_usage.py

Sources: examples/README.md:5-8

Python API Walkthrough

The following demonstrates the fundamental workflow using the Python API:

from mind_mem import recall, initialize_workspace

# Initialize workspace memory directory
workspace = "/path/to/project"
initialize_workspace(workspace)

# Search memory using BM25 recall
results = recall(
    workspace,
    "authentication design decision",
    limit=10,
    active_only=True
)

CLI Commands

The mm CLI provides five primary subcommands:

#### Recall Command

# Basic search
mm recall "authentication flow"

# With limit and active-only filter
mm recall "decision" --limit 5 --active-only

#### Context Command

Generates a token-budgeted snippet suitable for including in LLM context windows:

mm context "redis configuration" --max-tokens 2000

Sources: src/mind_mem/mm_cli.py:53-80

Agent Integration

Mind-mem supports multiple AI coding assistants through the hook installer system.

Supported Agents

Sources: src/mind_mem/hook_installer.py:80-150

Installing Agent Hooks

The hook installer generates configuration files and provides MCP server specifications:

from mind_mem.hook_installer import (
    mcp_server_spec,
    get_agent_spec,
    install_hooks
)

# Get MCP server invocation for your client
spec = mcp_server_spec(workspace="/path/to/project")
# Returns: {command, args, env}

# Install hooks for a specific agent
install_hooks("claude", workspace="/path/to/project")

MCP Server Path Resolution

The MCP server is located using this precedence:

graph TD
    A["MIND_MEM_MCP_SERVER<br/>env var"] --> B{File exists?}
    B -->|Yes| C["Use override path"]
    B -->|No| D["src-layout checkout<br/>../mcp_server.py"]
    D --> E{File exists?}
    E -->|No| F["Packaged install<br/>../mcp_server.py"]
    F --> G{File exists?}
    G -->|No| H["Package root<br/>mcp_server.py"]
    H --> I["Fallback: mcp_server.py"]

Sources: src/mind_mem/hook_installer.py:15-40

Web Console (Optional)

For visual exploration of memory, the web console provides a force-directed graph view:

cd web
pnpm install
pnpm dev

Access at http://localhost:3000.

Web Console Features

The console displays:

• Graph View: Force-directed visualization of block relationships
• Timeline View: Chronological event ordering
• Facts Panel: Extracted claims with confidence scores

All views derive from a single recall(format="bundle") call.

Sources: web/README.md:1-35

Configuration

Set the API URL if mind-mem isn't on localhost:8080:

NEXT_PUBLIC_MIND_MEM_API_URL=http://mind-mem.internal:8080 pnpm dev

Sources: web/README.md:14-18

MCP Resources

The MCP server exposes read-only resources for AI assistants:

Resources are registered after server construction to avoid circular imports.

Sources: src/mind_mem/mcp/resources.py:20-45

Next Steps

After completing this quick start guide:

1. Explore Memory Blocks: Create DECISIONS.md, TASKS.md, and SIGNALS.md files in your workspace
2. Configure Your Agent: Use the hook installer to integrate with your preferred AI assistant
3. Try Advanced Recall: Experiment with mm context for token-budgeted retrieval
4. Set Up Governance: Configure the governance workflow for memory evolution
5. Run the Web Console: Visualize your memory graph

File Structure Convention

Mind-mem expects this structure within your workspace:

workspace/
├── memory/           # User-authored memory blocks
│   ├── DECISIONS.md
│   ├── TASKS.md
│   └── SIGNALS.md
├── .mind/            # Kernel configuration files
└── mind-mem.json     # Feature flags and limits

Sources: examples/basic_usage.py:1-30

Troubleshooting

Common Issues

Debug Mode

Enable verbose logging by setting:

export MIND_MEM_LOG_LEVEL=DEBUG

Summary

This guide covered:

• Installation via pip editable mode
• Workspace initialization and environment variables
• Basic CLI commands (recall, context, inject, vault, status)
• Agent hook installation for AI assistant integration
• Optional web console setup
• MCP resources for programmatic access

For deeper integration, explore the governance tools, audit capabilities, and v4 cognitive features in the advanced documentation.

Related Pages

Related topics: Overview, Core Components, Hybrid Search & Retrieval

System Architecture

Overview

mind-mem is a persistent memory system designed for AI coding agents. It provides structured memory management through markdown-based block files, BM25 full-text search, graph-based relationship tracking, and an MCP (Model Context Protocol) server interface for seamless integration with AI coding clients.

The system follows a "memory is never modified except by governance" invariant, ensuring that all changes to the knowledge base go through a formal propose → approve → apply workflow. This architecture enables multi-agent collaboration while maintaining audit trails and preventing uncontrolled drift.

Sources: src/mind_mem/compiled_truth.py

High-Level Architecture

graph TB
    subgraph "Client Layer"
        CLI[mm CLI]
        MCP[MCP Clients<br/>Claude Code, Codex, Cursor, Windsurf]
        WebApp[Web Console]
    end

    subgraph "Interface Layer"
        MM_CLI[mm_cli.py<br/>Non-MCP Interface]
        MCPServer[MCP Server<br/>FastMCP]
        RestAPI[REST API v1]
    end

    subgraph "Core Engine"
        Recall[recall.py<br/>BM25 + Vector Recall]
        Graph[knowledge_graph.py<br/>Entity Relationships]
        BlockParser[block_parser.py<br/>Markdown Processing]
        ApplyEngine[apply_engine.py<br/>Change Application]
    end

    subgraph "Governance Layer"
        Governance[governance.py<br/>Proposals & Approvals]
        CompiledTruth[compiled_truth.py<br/>Truth Aggregation]
        AuditChain[audit_chain.py<br/>Integrity Verification]
    end

    subgraph "Data Layer"
        Workspace[(Workspace<br/>memory/ intelligence/ signals/)]
        FTS5[(FTS5 Index)]
        SQLite[(SQLite DB)]
    end

    CLI --> MM_CLI
    MCP --> MCPServer
    WebApp --> RestAPI

    MM_CLI --> Recall
    MCPServer --> Recall
    MCPServer --> Governance
    MCPServer --> ApplyEngine
    RestAPI --> Recall

    Recall --> BlockParser
    Recall --> Graph
    ApplyEngine --> BlockParser
    Governance --> CompiledTruth

    BlockParser --> Workspace
    Graph --> SQLite
    Recall --> FTS5

Directory Structure

mind-mem/
├── src/mind_mem/
│   ├── mcp/
│   │   ├── server.py              # Main MCP server entry point
│   │   ├── resources.py           # MCP resource declarations
│   │   └── tools/
│   │       ├── governance.py      # Propose, approve, rollback tools
│   │       ├── kernels.py         # Mind kernel configuration tools
│   │       ├── memory_ops.py      # Index, health, export tools
│   │       └── arch_mind.py       # Architecture baseline/delta tools
│   ├── recall.py                  # BM25 recall implementation
│   ├── knowledge_graph.py         # Entity extraction & relationships
│   ├── compiled_truth.py          # Compiled truth page management
│   ├── apply_engine.py            # Workspace modification engine
│   ├── block_parser.py            # Markdown block parsing
│   ├── mm_cli.py                  # CLI interface for non-MCP agents
│   ├── hook_installer.py          # Per-agent hook configuration
│   ├── model_provenance.py        # Model audit & provenance
│   └── v4/                        # v4.0 future capabilities
├── web/                           # Next.js web console
└── docs/

Core Components

Workspace Organization

The workspace is the root directory containing all memory files and metadata. It is resolved from the MIND_MEM_WORKSPACE environment variable or defaults to the current working directory.

Sources: src/mind_mem/mm_cli.py:28-32

graph TD
    W[(Workspace Root)]
    W --> |memory/| M[memory/<br/>DECISIONS.md<br/>TASKS.md<br/>entities/]
    W --> |intelligence/| I[intelligence/<br/>applied/ snapshots/]
    W --> |signals/| S[signals/<br/>SIGNALS.md]
    W --> |.mind/| MK[.mind/<br/>kernel configs/]
    W --> |mind-mem.json| CFG[mind-mem.json<br/>Configuration]

Block Parser

The block parser extracts structured information from markdown files, supporting various block types with frontmatter metadata.

Sources: src/mind_mem/mcp/tools/governance.py:24-26

Recall System

The recall system provides BM25-based full-text search across the workspace memory. It ranks results by relevance and supports filtering by block type and temporal constraints.

Sources: src/mind_mem/mm_cli.py:36-43

graph LR
    Q[Query] --> Recall
    Recall --> |BM25| FTS[FTS5 Index]
    Recall --> |parse| BP[block_parser.py]
    BP --> |active blocks| Filter
    FTS --> Filter
    Filter --> R[Ranked Results<br/>JSON bundle format]

MCP Server Architecture

The MCP server exposes tools and resources through the Model Context Protocol, enabling AI coding clients to interact with the memory system.

Sources: src/mind_mem/mcp/resources.py:1-29

MCP Resources

Resources provide read-only access to workspace data:

MCP Tool Categories

#### Governance Tools

Governance tools manage the propose → approve → apply lifecycle:

Sources: src/mind_mem/mcp/tools/governance.py:1-28

#### Memory Operations Tools

Memory operations provide lifecycle management:

Sources: src/mind_mem/mcp/tools/memory_ops.py:1-30

#### Kernel Tools

Kernel tools provide access to mind kernel configuration:

Sources: src/mind_mem/mcp/tools/kernels.py:1-27

#### Architecture Mind Tools

Arch-mind tools integrate architecture baseline management:

Sources: src/mind_mem/mcp/tools/arch_mind.py:1-40

Governance Workflow

The governance system ensures all memory modifications follow a controlled process:

graph LR
    A[Agent proposes<br/>propose_update] --> B{Signal created<br/>in signals/}
    B --> C{Human review}
    C -->|approve| D[dry-run]
    C -->|reject| E[Signal discarded]
    D -->|confirm| F[apply_engine.py]
    D -->|cancel| E
    F --> G[Snapshot created<br/>for rollback]
    G --> H[Changes applied<br/>to workspace]
    H --> I[Compiled truth<br/>recompiled]

Compiled Truth System

The compiled truth system aggregates evidence per entity into canonical understanding pages:

Sources: src/mind_mem/compiled_truth.py:1-50

# entity_id — Compiled Truth

## Current Understanding
- Bullet point summary from evidence

## Evidence Trail
### timestamp [CONF] (source: ...)
Observation text

Apply Engine

The apply engine handles workspace modifications through the configured BlockStore:

Sources: src/mind_mem/apply_engine.py:1-60

graph TD
    AE[apply_engine.py] --> BS{BlockStore<br/>mind-mem.json}
    BS -->|markdown| MS[MarkdownBlockStore]
    BS -->|postgres| PS[PostgresBlockStore]
    BS -->|encrypted| ES[EncryptedWrapper]
    MS --> WD[(Workspace<br/>Files)]
    PS --> PG[(PostgreSQL)]
    ES --> PS
    
    AE --> |create_snapshot| Snap
    AE --> |restore_snapshot| Rest
    AE --> |snapshot_diff| Diff

CLI Interface

The mm CLI provides a unified interface for non-MCP agents:

Sources: src/mind_mem/mm_cli.py:1-60

mm recall "<query>"             # Search memory
mm context "<query>"            # Generate token-budgeted snippet
mm inject --agent <name> "<q>"  # Render snippet for specific agent
mm vault scan <vault_root>      # List parsed vault blocks (JSON)
mm vault write <vault_root> <id> --type <t> --body <b>
mm status                       # Workspace summary

Web Console

The web console provides a visual interface for memory exploration:

Sources: web/README.md

graph TB
    Web[Next.js Console] --> API[lib/api.ts]
    API --> Recall[/v1/recall]
    API --> Health[/v1/health]
    
    Recall --> |bundle| GV[GraphView<br/>d3-force]
    Recall --> |bundle| TV[TimelineView<br/>Chronological]
    Recall --> |bundle| FL[FactList<br/>Extracted claims]

Agent Integration

The hook installer enables per-agent memory integration:

Sources: src/mind_mem/hook_installer.py:1-100

v4.0 Future Architecture

The v4.0 package provides side-by-side scaffolding, gated by feature flags:

Sources: src/mind_mem/v4/__init__.py

Key Design Principles

Related Pages

Related topics: System Architecture, Hybrid Search & Retrieval, Governance & Safety

Core Components

MIND-Mem's architecture centers on a set of interconnected components that manage workspace memory through a structured lifecycle: recall, storage, application, conflict resolution, drift detection, and tiered memory management. These components work together to provide a robust, multi-agent compatible memory system that maintains data integrity and supports autonomous memory consolidation.

Memory Recall System

The recall system is the primary retrieval engine in MIND-Mem, providing BM25-based full-text search over the workspace memory blocks. It supports flexible querying with result limiting and active-only filtering.

Recall Architecture

graph TD
    A[Query Input] --> B[recall function]
    B --> C[BM25 FTS5 Index]
    C --> D[Ranked Results]
    D --> E[Optional: pack_to_budget]
    E --> F[Token-Budgeted Snippet]

Recall Function

The recall() function serves as the main entry point for memory retrieval:

def recall(workspace, query, limit=10, active_only=True)

Sources: src/mind_mem/recall.py

Context Generation

The pack_to_budget() function from cognitive_forget module works with recall results to generate token-budgeted snippets for efficient context injection:

from mind_mem.cognitive_forget import pack_to_budget
results = recall(workspace, query)
context = pack_to_budget(results, token_budget)

Sources: src/mind_mem/recall.py

Block Storage Layer

The block storage layer provides an abstraction over different storage backends, enabling MIND-Mem to work with Markdown files on disk or optional PostgreSQL deployments.

Storage Backend Selection

graph TD
    A[get_block_store workspace] --> B{Try Import storage module}
    B -->|Success| C[Return configured backend]
    B -->|Exception| D[Fallback to MarkdownBlockStore]
    C --> E[Markdown / Postgres / Encrypted]

BlockStore Implementations

Sources: src/mind_mem/block_store.py

Block Deletion and Recovery

The storage layer maintains an append-only deletion log for recovery:

def _log_block_deletion(workspace, block_id, content):
    """Append deletion receipt to memory/deleted_blocks.jsonl."""
    log_path = os.path.join(workspace, "memory", "deleted_blocks.jsonl")
    entry = {
        "block_id": block_id,
        "deleted_at": datetime.now(timezone.utc).isoformat(),
        "content": content,
    }

Block locations are determined by scanning text content for block ID headers [block_id], with boundaries at next headers or --- separators.

Sources: src/mind_mem/block_store.py

Apply Engine

The apply engine handles workspace modifications through a staged proposal and apply workflow, supporting snapshots, rollback, and diff operations.

Application Workflow

graph LR
    A[propose_update] --> B[Signal Written]
    B --> C[approve_apply]
    C --> D{Snapshot Created}
    D -->|Success| E[Changes Applied]
    D -->|Failure| F[Rollback Available]

Snapshot Operations

The apply engine routes through the configured BlockStore, allowing Postgres-backed deployments to snapshot via SQL instead of on-disk copies.

Sources: src/mind_mem/apply_engine.py

Block Store Routing

def _store_for(ws):
    """Route to the configured BlockStore implementation."""
    try:
        from .storage import get_block_store
        return get_block_store(ws)
    except Exception:
        return MarkdownBlockStore(ws)  # Fallback resilience

This fallback mechanism keeps the apply engine resilient on first-run or misconfigured workspaces.

Sources: src/mind_mem/apply_engine.py

Conflict Resolution

The conflict resolver manages situations where multiple agents or processes attempt to modify the same memory blocks, ensuring data consistency and preventing silent overwrites.

Resolution Strategy

The conflict resolver implements a last-write-wins (LWW) strategy with evidence preservation, allowing the system to track and potentially rollback conflicting changes.

Key Operations

Sources: src/mind_mem/conflict_resolver.py

Drift Detection

The drift detector monitors memory state changes over time, identifying when factual understanding diverges from previously recorded information.

Drift Detection Pipeline

graph TD
    A[Memory Blocks] --> B[Baseline Snapshot]
    B --> C[Current State]
    C --> D[Comparison Engine]
    D --> E{Drift Detected?}
    E -->|Yes| F[Flag for Review]
    E -->|No| G[Continue Monitoring]

Detection Criteria

Sources: src/mind_mem/drift_detector.py

Tiered Memory

The tiered memory system organizes memory blocks across multiple storage tiers based on access patterns, importance, and staleness, enabling efficient resource utilization.

Memory Tier Structure

graph BT
    A[Hot Tier] --> B[Warm Tier]
    B --> C[Cold Tier]
    A --> D[Active Memory]
    B --> E[Archived Memory]
    C --> F[Long-term Storage]

Tier Classification

The consolidation system uses ConsolidationConfig to control the forgetting cycle:

cfg = ConsolidationConfig(
    importance_threshold=0.25,
    stale_days=14,
    archive_after_days=60,
    grace_days=30,
)

Sources: src/mind_mem/tiered_memory.py

MCP Core Tools

The MCP (Model Context Protocol) layer exposes core functionality as tools for agent integration. The core tools module provides the primary interface for memory operations.

Available Core Tools

Kernel Configuration Loading

from mind_mem.mind_ffi import get_mind_dir, load_all_kernel_configs, load_kernel_config

mind_dir = get_mind_dir(workspace)
all_cfgs = load_all_kernel_configs(mind_dir)

The .mind kernel files tune recall, reranking, RM3 expansion, and related pipeline knobs.

Sources: src/mind_mem/mcp/tools/core.py

Quality Gate

The quality gate provides a deterministic pre-storage filter for candidate blocks, ensuring memory integrity through content validation.

Quality Rules

Quality gate modes:

Configuration sources (in priority order): strict=True keyword argument → QualityGateConfig(mode="strict") → mind-mem.json setting quality_gate_mode = "strict".

Sources: src/mind_mem/quality_gate.py

Compiled Truth System

The compiled truth system aggregates evidence per entity and recompiles canonical understanding from source memory blocks.

Truth Page Format

Related Pages

Related topics: Knowledge Graph & Entity Management, Core Components, Block Format & Data Model

Hybrid Search & Retrieval

Overview

The Hybrid Search & Retrieval system in mind-mem provides multi-modal memory retrieval capabilities that combine keyword-based search (BM25), dense vector search, graph-based traversal, and intelligent reranking to deliver contextually relevant results for AI agents and CLI operations.

The system operates under the principle that no single retrieval method is optimal for all query types. By combining multiple retrieval strategies with Reciprocal Rank Fusion (RRF), mind-mem achieves robust and accurate recall across diverse query patterns.

Architecture Overview

graph TD
    A[Query Input] --> B[Intent Router]
    B --> C{Query Type}
    C -->|Keyword| D[BM25 / FTS5]
    C -->|Semantic| E[Vector Recall]
    C -->|Graph| F[Graph Recall]
    D --> G[Query Expansion]
    E --> G
    F --> G
    G --> H[Hybrid Recall]
    H --> I[Cross-Encoder Reranker]
    I --> J[Final Results]
    
    K[Graph DB] --> F
    L[FTS5 Index] --> D
    M[Vector Store] --> E

Core Components

Intent Router

The Intent Router (intent_router.py) classifies incoming queries to determine the optimal retrieval strategy.

Responsibilities:

• Analyze query semantics to determine intent
• Route queries to appropriate retrieval backends
• Support mixed-mode retrieval when query intent is ambiguous

Routing Decisions:

Sources: src/mind_mem/intent_router.py

BM25 Keyword Search

BM25 (Best Matching 25) provides traditional keyword-based retrieval through SQLite FTS5. This approach excels at exact term matching and is the default retrieval method for the CLI recall command.

Key Features:

• Term frequency/inverse document frequency scoring
• Configurable BM25 parameters via .mind kernel files
• Integration with the recall function for workspace queries

Usage in CLI:

def _cmd_recall(args: argparse.Namespace) -> int:
    from mind_mem.recall import recall
    results = recall(_workspace(), args.query, limit=args.limit, active_only=args.active_only)
    print(json.dumps(results, indent=2, default=str))
    return 0

Sources: src/mind_mem/mm_cli.py:42-47

Vector Recall

Dense vector retrieval (recall_vector.py) provides semantic similarity search using embeddings. This method identifies conceptually related content even when exact terms differ.

Capabilities:

• Dense embedding-based similarity scoring
• Configurable embedding model selection
• Fallback to BM25 when vector search unavailable

Integration Points:

• Called by hybrid recall orchestrator
• Results fed into cross-encoder reranking pipeline
• Supports workspace-specific vector stores

Sources: src/mind_mem/recall_vector.py

Graph Recall

Graph-based recall (graph_recall.py) traverses the co-retrieval graph to discover related memory blocks based on entity relationships and cross-reference patterns.

Algorithm Overview:

graph LR
    A[Query Block] --> B[Find Connected Nodes]
    B --> C[Weighted Edge Traversal]
    C --> D[Collect Related Blocks]
    D --> E[Score by Path Length]
    
    F[Co-Retrieval DB] --> B

Features:

• Kahn's algorithm for topological ordering
• Cycle breaking on lowest-weight edges
• Chronological backbone combined with co-retrieval edges

The graph recall is particularly valuable for "walkthrough" scenarios where temporal dependencies matter:

For teach me / explain queries, agents and humans both want a learning order — foundations first, then derived context, then current state.

Sources: src/mind_mem/graph_recall.py

Query Expansion

Query expansion (query_expansion.py) enhances the original query with related terms, synonyms, and context to improve recall coverage.

Expansion Strategies:

• Synonym injection based on domain knowledge
• Entity-aware term expansion
• Contextual query reformulation

Sources: src/mind_mem/query_expansion.py

Hybrid Recall Orchestration

RRF (Reciprocal Rank Fusion)

The hybrid recall module (hybrid_recall.py) combines results from multiple retrieval methods using Reciprocal Rank Fusion. RRF provides a simple yet effective way to merge ranked lists without requiring score normalization.

RRF Formula:

score(d) = Σ 1 / (k + rank_i(d))

Where k is typically 60, and rank_i(d) is the rank of document d in retrieval list i.

Benefits:

• No need for score calibration between methods
• Robust to individual method failures
• Emphasizes documents ranked well across multiple sources

Sources: src/mind_mem/hybrid_recall.py

Integration with MCP Resources

The MCP (Model Context Protocol) layer exposes recall functionality as resources:

"""mind-mem://recall/{query}  — BM25 recall search"""

This enables MCP-aware AI clients to request memory context directly through the standardized resource interface.

Sources: src/mind_mem/mcp/resources.py

Reranking Pipeline

Cross-Encoder Reranker

The cross-encoder reranker (cross_encoder_reranker.py) applies a trained model to re-score retrieved candidates against the original query, significantly improving ranking quality.

Pipeline Position:

graph LR
    A[Hybrid Recall] --> B[Cross-Encoder Rerank]
    B --> C[Final Ranking]

Processing Flow:

1. Receive top-N candidates from hybrid recall (e.g., top 100)
2. Score each candidate against the query using cross-encoder
3. Re-rank by cross-encoder scores
4. Return top-K final results (typically K < N)

Cross-Encoder Advantages:

• Captures query-document interaction features
• Better handles complex semantic relationships
• Can incorporate attention mechanisms for relevance

Sources: src/mind_mem/cross_encoder_reranker.py

Scoring System

Score Composition

The final relevance score combines multiple signals:

Scoring Configuration

Mind-mem uses .mind kernel files to configure retrieval parameters. The bm25.mind file controls BM25-specific settings while rrf.mind manages fusion parameters.

Sources: docs/scoring.md

MCP Tools Integration

Memory Operations Tools

The MCP layer provides programmatic access to recall functionality:

Sources: src/mind_mem/mcp/tools/memory_ops.py

CLI Usage

Recall Command

mm recall "query"             # search memory
mm recall "query" --limit 10 # limit results
mm recall "query" --active-only # exclude archived blocks

Context Command

The context command generates token-budgeted snippets using cognitive forgetting logic to pack relevant content within token constraints.

mm context "query"           # generate budgeted context

Sources: src/mind_mem/mm_cli.py

Configuration

Kernel Files

Retrieval behavior is tuned through .mind kernel configuration files:

The kernel loader supports hot-reloading for runtime tuning:

from mind_mem.mind_ffi import load_kernel_config, get_mind_dir

mind_dir = get_mind_dir(workspace)
cfg = load_kernel_config(mind_dir, "rrf")

Sources: src/mind_mem/mcp/tools/kernels.py

Performance Considerations

Index Maintenance

• FTS5 indices support incremental updates
• Periodic reindexing recommended for optimal performance
• Vector indices may require periodic re-embedding for freshness

Latency Optimization

• Hybrid recall executes multiple retrieval paths in parallel
• Cross-encoder reranking applied only to top-N candidates
• Caching of frequent query patterns recommended

Related Documentation

• Scoring System — Detailed scoring algorithms
• Walkthrough Module — Dependency-ordered retrieval for teaching
• Quality Gate — Block quality filtering before storage

Related Pages

Related topics: Hybrid Search & Retrieval, Governance & Safety, Block Format & Data Model

Knowledge Graph & Entity Management

Overview

The Knowledge Graph & Entity Management system in mind-mem provides a structured mechanism for capturing, organizing, and querying relationships between entities in the workspace. It extends the basic block storage model with typed edges, entity ontologies, compiled truth pages, and contradiction detection capabilities.

This system serves multiple purposes:

• Relationship Tracking: Records typed relationships (subject-predicate-object triples) between blocks and entities
• Entity Classification: Defines and validates entity types through an ontology registry
• Truth Compilation: Aggregates evidence from multiple sources into canonical entity understanding
• Contradiction Detection: Identifies conflicting claims across evidence entries
• Causal Analysis: Tracks dependency relationships between blocks for impact analysis

Sources: src/mind_mem/mcp/tools/graph.py:1-17

Architecture

graph TD
    subgraph "Data Layer"
        KG[Knowledge Graph<br/>retrieval_graph.db]
        CG[Causal Graph<br/>causal_graph.db]
        TP[Truth Pages<br/>truth/ directory]
        ONT[Ontology<br/>Registry]
    end

    subgraph "Ingestion Layer"
        EI[Entity Ingest]
        BD[Block Store]
        CD[Contradiction<br/>Detector]
    end

    subgraph "MCP Tools"
        GQ[graph_query]
        GTA[graph_add_edge]
        TGG[traverse_graph]
        CTL[compiled_truth_load]
        CTA[compiled_truth_add_evidence]
        CTC[compiled_truth_contradictions]
    end

    EI --> ONT
    BD --> KG
    BD --> CG
    KG --> GQ
    CG --> TGG
    TP --> CTL
    TP --> CTA
    CD --> CTC

    style KG fill:#e1f5fe
    style CG fill:#e8f5e8
    style TP fill:#fff3e0
    style ONT fill:#fce4ec

Knowledge Graph

Core Data Model

The knowledge graph stores typed edges between entities using SQLite. Each edge contains:

Sources: src/mind_mem/mcp/tools/graph.py:20-45

Predicate Types

The system supports predefined predicate types through the Predicate enum:

class Predicate(str, Enum):
    """Predefined relationship types for the knowledge graph."""
    DEPENDS_ON = "depends_on"
    RELATED_TO = "related_to"
    PART_OF = "part_of"
    IMPLEMENTS = "implements"
    CONTRADICTS = "contradicts"
    REFERENCES = "references"
    CAUSED_BY = "caused_by"

Sources: src/mind_mem/knowledge_graph.py (inferred from usage patterns)

MCP Tools for Knowledge Graph

#### graph_add_edge

Records a typed relationship in the knowledge graph.

Parameters:

Returns:

{
  "_schema_version": "3.2.0",
  "subject": "PROJECT-A",
  "predicate": "depends_on",
  "object": "PROJECT-B",
  "confidence": 0.95,
  "edge_id": 42
}

Sources: src/mind_mem/mcp/tools/graph.py:30-80

#### graph_query

Performs N-hop traversal queries on the knowledge graph.

Parameters:

Sources: src/mind_mem/mcp/tools/graph.py:80-150

#### graph_stats

Returns aggregate statistics about the knowledge graph.

Returns:

{
  "total_edges": 156,
  "predicates": {
    "depends_on": 45,
    "related_to": 67,
    "references": 44
  },
  "unique_subjects": 89,
  "unique_objects": 102
}

Sources: src/mind_mem/mcp/tools/graph.py:150-200

Entity Management

Ontology Registry

The ontology system defines entity types with their required and optional properties:

classDiagram
    class EntityType {
        +str name
        +str parent
        +tuple required
        +tuple optional
        +dict property_types
        +validate(data) bool
    }

    class Ontology {
        +str name
        +str version
        +dict~str, EntityType~ entity_types
        +get_type(name) EntityType
        +register(entity_type) None
    }

    class OntologyRegistry {
        +list ontologies
        +get_default() Ontology
        +register(ontology) None
    }

    OntologyRegistry "1" --> "*" Ontology
    Ontology "1" --> "*" EntityType
    EntityType --> EntityType : inherits from

Sources: src/mind_mem/ontology.py

Built-in Entity Types

Sources: src/mind_mem/ontology.py

Entity Ingestion

Entities are ingested through the entity_ingest module which:

1. Parses incoming entity data
2. Validates against the active ontology
3. Updates or creates entity records
4. Links entities to their source blocks

Sources: src/mind_mem/entity_ingest.py

Compiled Truth Pages

Compiled Truth Pages aggregate evidence from multiple sources into canonical understanding for each entity. This follows a "memory is never modified except by governance" principle.

Data Model

classDiagram
    class CompiledTruthPage {
        +str entity_id
        +str entity_type
        +str compiled_section
        +list evidence_entries
        +str last_compiled
        +int version
    }

    class EvidenceEntry {
        +str timestamp
        +str source
        +str observation
        +str confidence
        +bool superseded
    }

    CompiledTruthPage "1" --> "*" EvidenceEntry

Sources: src/mind_mem/compiled_truth.py

Evidence Entry Fields

Sources: src/mind_mem/compiled_truth.py:1-50

Truth Page Format

Truth pages are stored as Markdown with YAML frontmatter:

Related Pages

Related topics: Core Components, Key Concepts, Block Format & Data Model

Governance & Safety

The mind-mem system implements a multi-layered governance and safety architecture designed to ensure memory integrity, prevent contradictions, detect drift, and enforce quality standards before any block enters the system. The core invariant is: "memory is never modified except by governance" — meaning every change to the memory state requires explicit approval through a controlled workflow.

Architecture Overview

The governance and safety subsystem spans several interconnected components:

graph TD
    subgraph "Ingestion Layer"
        QG[Quality Gate]
        AC[Abstention Classifier]
        GG[Governance Gate]
    end
    
    subgraph "Integrity Layer"
        CT[Compiled Truth]
        CD[Contradiction Detector]
        DD[Drift Detector]
    end
    
    subgraph "Audit Layer"
        AU[Audit Chain]
        MH[Merkle Hash]
    end
    
    subgraph "MCP Tools"
        PRO[propose_update]
        APP[approve_apply]
        ROLL[rollback_proposal]
        SCAN[scan]
        LIST_CON[List Contradictions]
    end
    
    QG -->|block review| GG
    AC -->|abstain if uncertain| QG
    GG -->|staged proposal| PRO
    PRO -->|pending| APP
    APP -->|apply| CT
    CT -->|evidence| CD
    CT -->|evidence| DD
    AU -->|genesis block| MH
    MH -->|verify| AU
    
    SCAN -->|run all checks| CD
    SCAN -->|run all checks| DD
    LIST_CON -->|contradiction list| CD

Sources: src/mind_mem/mcp/tools/governance.py:1-15

Core Governance Invariants

The Memory Modification Rule

The fundamental governance rule is explicit:

"Memory is never modified except by governance"

This means:

1. No agent can directly write or modify memory blocks
2. All modifications must go through the governance workflow
3. The governance workflow includes staged proposals, human review, and audit trails
4. Rollback capabilities exist to restore from pre-apply snapshots

Sources: src/mind_mem/mcp/tools/governance.py:17-20

Governance Workflow States

stateDiagram-v2
    [*] --> Proposed: propose_update
    Proposed --> Approved: approve_apply
    Proposed --> Rejected: reject
    Approved --> Applied: execute
    Applied --> [*]
    Proposed --> RolledBack: rollback_proposal
    Rejected --> [*]
    RolledBack --> [*]

Quality Gate

The quality gate is a pre-storage filter that inspects candidate blocks before they enter the system. It implements 8 deterministic, content-based rules.

Sources: src/mind_mem/quality_gate.py:1-20

Quality Rules

Quality Gate Modes

The quality gate operates in two modes:

Sources: src/mind_mem/quality_gate.py:20-45

Abstention Classifier

The abstention classifier provides an uncertainty-aware filtering layer that can abstain from processing when confidence is insufficient.

Sources: src/mind_mem/abstention_classifier.py:1-10

Compiled Truth System

The compiled truth system aggregates evidence per entity and recompiles canonical understanding. Each truth page contains:

Data Model

@dataclass
class CompiledTruthPage:
    entity_id: str           # Entity identifier
    entity_type: str        # Type classification
    compiled_section: str    # Regenerated summary
    evidence_entries: list   # All evidence items
    last_compiled: str      # ISO timestamp
    version: int            # Increments on recompile

Evidence Entry Structure

@dataclass
class EvidenceEntry:
    timestamp: str       # ISO timestamp
    source: str          # Source identifier
    observation: str     # The factual observation
    confidence: str      # Confidence level
    superseded: bool     # Whether this entry is superseded

Compiled Truth Workflow

graph LR
    subgraph "Evidence Collection"
        OBS[New Observation] --> ADD[compiled_truth_add_evidence]
    end
    
    subgraph "Recompilation"
        ADD --> REQ[recompile_truth]
        REQ --> GEN[Generate bullet summary]
        REQ --> INC[Increment version]
        REQ --> UPDATE[Update last_compiled]
    end
    
    subgraph "Output"
        GEN --> PAGE[Compiled Truth Page]
        INC --> PAGE
        UPDATE --> PAGE
    end

Key Functions

Sources: src/mind_mem/compiled_truth.py:1-150

Contradiction Detection

The contradiction detector identifies conflicts within compiled truth pages and across the memory system.

Detection Capabilities

• Intra-page contradictions: Conflicting evidence within a single entity's truth page
• Cross-page contradictions: Conflicts between different entities
• Temporal conflicts: Evidence that contradicts based on timing
• Confidence-weighted detection: Higher confidence evidence takes precedence

Contradiction Result Structure

@dataclass
class ContradictionFinding:
    entity_id: str              # Affected entity
    type: str                   # e.g., "temporal", "factual", "confidence"
    evidence_a: EvidenceEntry   # First conflicting entry
    evidence_b: EvidenceEntry   # Second conflicting entry
    resolution_hint: str         # Suggested resolution

Sources: src/mind_mem/contradiction_detector.py:1-30

Drift Detection

Drift detection monitors for changes in memory that deviate from established patterns or governance-approved state.

Drift Categories

Sources: src/mind_mem/drift_detector.py:1-25

Audit Chain

The audit chain maintains a cryptographic record of all governance actions using SHA3-512 hashing.

Audit Chain Components

graph TD
    subgraph "Genesis Block"
        GB[Genesis Hash]
    end
    
    subgraph "Audit Records"
        A1[Action 1 Record]
        A2[Action 2 Record]
        A3[Action 3 Record]
    end
    
    subgraph "Hash Chain"
        GB --> H1[Hash 1]
        H1 --> H2[Hash 2]
        H2 --> H3[Hash 3]
    end
    
    A1 --> H1
    A2 --> H2
    A3 --> H3

Verification Capabilities

Sources: src/mind_mem/audit_chain.py:1-50

Governance MCP Tools

The governance functionality is exposed through MCP (Model Context Protocol) tools for agent integration.

Sources: src/mind_mem/mcp/tools/governance.py:1-25

Tool Reference

`propose_update` Parameters

`approve_apply` Parameters

`rollback_proposal` Parameters

Sources: src/mind_mem/mcp/tools/governance.py:30-100

Governance Health Benchmark

The governance health benchmark (governance_health_bench) exercises the full governance system:

graph TD
    GB[governance_health_bench] --> CD[Contradiction Detection]
    GB --> AC[Audit Completeness]
    GB --> DD[Drift Detection]
    GB --> SC[Scalability Probes]
    
    CD --> CR{Results}
    AC --> CR
    DD --> CR
    SC --> CR
    
    CR --> JSON[JSON Report]

Benchmark Sub-Suites

Sources: src/mind_mem/mcp/tools/benchmark.py:1-40

Configuration

Workspace Configuration

The governance system respects workspace-level configuration in mind-mem.json:

{
  "quality_gate_mode": "advisory",
  "contradiction_detection": {
    "enabled": true,
    "min_confidence_threshold": "medium"
  },
  "drift_detection": {
    "enabled": true,
    "drift_threshold": 0.15
  }
}

Kernel Configuration

MIND kernel files in .mind format control governance behavior:

Sources: mind/governance.mind:1-30

MCP Resources

Governance state is also exposed as read-only MCP resources:

Sources: src/mind_mem/mcp/resources.py:1-40

Error Handling

Structured Error Envelope

All governance tools return a consistent error format:

{
  "_schema_version": "3.2.0",
  "error": "Human-readable error message"
}

Common Error Scenarios

Sources: src/mind_mem/mcp/tools/kernels.py:60-80

Metrics and Observability

Governance operations emit metrics for monitoring:

Sources: src/mind_mem/mcp/tools/kernels.py:35-40

See Also

• Memory System — Core memory storage and retrieval
• MCP Tools — MCP tool reference
• CLI Reference — mm command-line interface
• Protection — Safety mechanisms and thresholds

Related Pages

Related topics: Key Concepts, Hybrid Search & Retrieval

Block Format & Data Model

Overview

The mind-mem system uses a Markdown-based block format as its primary data model for storing and retrieving structured knowledge. Each block is a self-contained unit of information stored as Markdown text with a specific header format and field structure. This design enables human readability, git-friendly versioning, and flexible querying through the recall system.

Sources: src/mind_mem/block_store.py:1-50

Block Structure

Anatomy of a Block

A mind-mem block consists of three main parts:

[UNIQUE_BLOCK_ID]
Field1: value
Field2: value
ListField:
- item1
- item2
Tags: tag1, tag2

The MCP Server & Tools layer is the primary interface through which AI agents interact with the mind-mem workspace. Built on the FastMCP framework, this component exposes the entire memory system's capabilities—including recall, governance, consolidation, and knowledge management—as a standardized Model Context Protocol (MCP) surface that any MCP-compatible AI client (Claude Code, Cursor, Windsurf, Codex CLI, etc.) can consume.

Architecture Overview

The MCP layer is organized as a modular plugin architecture under src/mind_mem/mcp/:

mcp/
├── server.py              # FastMCP server entry point
├── resources.py           # @mcp.resource declarations
├── infra/
│   ├── rate_limit.py      # Rate limiting infrastructure
│   └── http_auth.py       # HTTP authentication
└── tools/
    ├── recall.py          # Memory recall & search
    ├── governance.py      # Decision/task governance
    ├── memory_ops.py      # Index & lifecycle management
    ├── kernels.py         # MIND kernel configuration
    ├── consolidation.py   # Memory consolidation
    ├── core.py            # Context-core bundle management
    ├── benchmark.py       # Governance health benchmarks
    ├── audit.py           # Compliance & drift detection
    └── arch_mind.py       # Architecture metrics wrapper

Server Initialization Pattern

The server uses a deferred registration pattern to avoid circular imports. Tools and resources are defined as module-level functions, then wired onto the FastMCP instance via a register(mcp) function call after the server instance is constructed.

# Resources use module-level definition
def get_decisions() -> str:
    """Active decisions from DECISIONS.md"""
    ...

# Registration happens after server construction
def register(mcp: FastMCP) -> None:
    mcp.resource("mind-mem://decisions")(get_decisions)

This pattern ensures that test files referencing server.get_decisions continue to work without triggering import-time circular dependencies. Sources: src/mind_mem/mcp/resources.py:1-47

MCP Resources

MCP Resources provide read-only views over the workspace filesystem. They expose the structured content of workspace documents as consumable data without requiring file I/O on the client side.

Available Resources

The resource module consolidates all eight resource types into a single file because each body is small (5–15 lines), they share the same imports, and they form a cohesive read-only surface. Sources: src/mind_mem/mcp/resources.py:1-47

MCP Tools

MCP Tools expose the full operational surface of the mind-mem system. They are organized by domain into eight functional areas.

Tool Registration Pattern

All tools are decorated with @mcp_tool_observe for observability, which wraps the function to emit metrics and structured logging. Tools also support tracing via the @_traced decorator for detailed request tracking.

@mcp_tool_observe
@_traced("tool_name")
def tool_name(param: str) -> str:
    """Tool description."""
    ws = _workspace()
    # implementation
    return json.dumps(result, indent=2)

Tool Domains

Recall Tools

Recall tools provide the primary memory retrieval surface. They support multiple retrieval backends and output formats.

The recall implementation supports three retrieval backends:

• auto (default): System selects based on query characteristics
• bm25: Classic bag-of-words relevance ranking
• hybrid: Combines BM25 with semantic similarity

Output formats include text (human-readable) and json (structured). Sources: src/mind_mem/mm_cli.py:1-100

Governance Tools

Governance tools implement the "memory is never modified except by governance" invariant. They provide a staged update workflow where changes are proposed, reviewed, and then applied atomically.

Governance Workflow

graph TD
    A[propose_update] --> B{Review}
    B -->|Approve| C[approve_apply]
    B -->|Reject| D[rollback_proposal]
    C --> E[Snapshot Created]
    E --> F[Changes Applied]
    F --> G[Audit Log Updated]
    D --> H[Workspace Restored]

The governance system maintains append-only audit logs and supports atomic rollback through workspace snapshots. Sources: src/mind_mem/mcp/tools/governance.py:1-60

Memory Operations Tools

Memory operations tools manage the workspace lifecycle and provide introspection capabilities.

Deletion operations are atomic and maintain an append-only recovery log for disaster recovery. The export tool supports size capping to prevent unbounded output when dumping large workspaces. Sources: src/mind_mem/mcp/tools/memory_ops.py:1-80

MIND Kernel Tools

MIND Kernel tools provide read-write access to .mind configuration files that tune recall, reranking, RM3 expansion, and related pipeline knobs.

These tools interact with the FFI layer (mind_ffi) to load and persist kernel configurations stored in the workspace's .mind/ directory. Sources: src/mind_mem/mcp/tools/kernels.py:1-70

Consolidation Tools

Consolidation tools implement the "memory settles over time" principle through cognitive forgetting and autonomous enrichment.

The consolidation cycle analyzes block importance scores, identifies candidates for archival, and optionally auto-repairs broken citations. Configuration parameters include:

• importance_threshold (default: 0.25)
• stale_days (default: 14)
• archive_after_days (default: 60)
• grace_days (default: 30)

graph LR
    A[Memory Blocks] --> B[Importance Scoring]
    B --> C{Threshold Check}
    C -->|Low Importance| D[Staleness Propagation]
    C -->|High Importance| E[Retain]
    D --> F[Archive Candidates]
    F --> G[Broken Citation Scan]
    G --> H[Auto-Repair]

Sources: src/mind_mem/mcp/tools/consolidation.py:1-60

Benchmark Tools

Benchmark tools provide governance health validation and category analysis.

The governance health benchmark exercises the full suite of validation checks and returns aggregated pass/fail counts per sub-suite. Sources: src/mind_mem/mcp/tools/benchmark.py:1-60

Core Tools

Core tools manage the .mmcore bundle lifecycle for portable block and knowledge-graph archives.

Bundles support namespace prefixing for block isolation when loading cores from different sources. Sources: src/mind_mem/mcp/tools/core.py:1-60

Architecture Metrics Tools (arch-mind)

Arch-mind tools wrap the arch-mind binary to expose architecture quality metrics as MCP tools.

The binary is located via the ARCH_MIND_BIN environment variable, falling back to PATH lookup. These tools delegate all metric arithmetic to the binary, which enforces the canonical AST schema and Q16.16 determinism contract. Sources: src/mind_mem/mcp/tools/arch_mind.py:1-60

CLI Interface (mm)

The mm CLI provides unified access to mind-mem for non-MCP agents. It mirrors the MCP tool surface with command-line equivalents.

Available Commands

The workspace is resolved via MIND_MEM_WORKSPACE environment variable, defaulting to cwd if unset. Sources: src/mind_mem/mm_cli.py:1-100

Compiled Truth System

The compiled truth system aggregates evidence per entity and maintains a canonical understanding that recompiles when new evidence is added.

Data Model

@dataclass
class CompiledTruthPage:
    entity_id: str
    entity_type: str
    compiled_section: str      # Canonical understanding
    evidence_entries: list[EvidenceEntry]
    last_compiled: str         # ISO timestamp
    version: int

@dataclass
class EvidenceEntry:
    timestamp: str
    source: str
    observation: str
    confidence: str           # "high", "medium", "low"
    superseded: bool

Compiled Truth Format

Truth pages are stored as markdown with frontmatter:

Doramagic Pitfall Log

Doramagic extracted 16 source-linked risk signals. Review them before installing or handing real data to the project.

1. Installation risk: PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks)

• Severity: medium
• Finding: Installation risk is backed by a source signal: PG-backed: mm doctor --rebuild-cache errors=263 (no such table: blocks). Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/star-ga/mind-mem/issues/524

2. Installation risk: PG-backed: `mm recall` returns [] despite direct PG FTS finding matches

• Severity: medium
• Finding: Installation risk is backed by a source signal: PG-backed: mm recall returns [] despite direct PG FTS finding matches. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/star-ga/mind-mem/issues/525

3. Installation risk: Perf regression: build_index on a fresh 80KB workspace takes ~55s

• Severity: medium
• Finding: Installation risk is backed by a source signal: Perf regression: build_index on a fresh 80KB workspace takes ~55s. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/star-ga/mind-mem/issues/530

4. Configuration risk: Configuration risk needs validation

• Severity: medium
• Finding: Configuration risk is backed by a source signal: Configuration risk needs validation. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.host_targets | github_repo:1160652179 | https://github.com/star-ga/mind-mem | host_targets=mcp_host, claude, claude_code, cursor

5. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:1160652179 | https://github.com/star-ga/mind-mem | README/documentation is current enough for a first validation pass.

6. Maintenance risk: test_rollback_removes_new_files fails on macOS + Windows runners (passes on Linux)

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: test_rollback_removes_new_files fails on macOS + Windows runners (passes on Linux). Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/star-ga/mind-mem/issues/515

7. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1160652179 | https://github.com/star-ga/mind-mem | last_activity_observed missing

8. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | github_repo:1160652179 | https://github.com/star-ga/mind-mem | no_demo; severity=medium

9. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | github_repo:1160652179 | https://github.com/star-ga/mind-mem | no_demo; severity=medium

10. Security or permission risk: ACL `_get_request_scope` fail-open on token-introspection exception (acl.py:139-142)

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: ACL _get_request_scope fail-open on token-introspection exception (acl.py:139-142). Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/star-ga/mind-mem/issues/526

11. Security or permission risk: FederationClient: no scheme allowlist, no redirect cap, no response-size cap, no TLS pinning (federation_client.py:240-…

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: FederationClient: no scheme allowlist, no redirect cap, no response-size cap, no TLS pinning (federation_client.py:240-…. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/star-ga/mind-mem/issues/529

12. Security or permission risk: THREE_WAY_MERGE doesn't bump vclock — resolved conflicts recur on every detect_conflict pass (federation.py:359-360)

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: THREE_WAY_MERGE doesn't bump vclock — resolved conflicts recur on every detect_conflict pass (federation.py:359-360). Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/star-ga/mind-mem/issues/527

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using mind-mem with real data or production workflows.

• Perf regression: build_index on a fresh 80KB workspace takes ~55s - github / github_issue
• FederationClient: no scheme allowlist, no redirect cap, no response-size - github / github_issue
• _handle_fed_resolve accepts caller-supplied merged_payload without val - github / github_issue
• THREE_WAY_MERGE doesn't bump vclock — resolved conflicts recur on every - github / github_issue
• ACL _get_request_scope fail-open on token-introspection exception (acl - github / github_issue
• [PG-backed: mm recall returns [] despite direct PG FTS finding matches](https://github.com/star-ga/mind-mem/issues/525) - github / github_issue
• PG-backed: mm doctor --rebuild-cache errors=263 (no such table: blocks - github / github_issue
• test_rollback_removes_new_files fails on macOS + Windows runners (passes - github / github_issue
• [[MEDIUM] N-03: Rate limiter collapses all stdio clients into 'default' b](https://github.com/star-ga/mind-mem/issues/513) - github / github_issue
• [[MEDIUM] T-003: propose_update input bounds bypass (rationale/tags writt](https://github.com/star-ga/mind-mem/issues/512) - github / github_issue
• [[MEDIUM] N-04: staged_change rollback dispatcher silently drops 'reason'](https://github.com/star-ga/mind-mem/issues/511) - github / github_issue
• [[MEDIUM] N-02: REST rollback_proposal silently drops 'reason' field](https://github.com/star-ga/mind-mem/issues/510) - github / github_issue