# https://github.com/star-ga/mind-mem 项目说明书
生成时间：2026-05-17 19:29:27 UTC
## 目录
- [Overview](#page-overview)
- [Key Concepts](#page-key-concepts)
- [Quick Start Guide](#page-quickstart)
- [System Architecture](#page-architecture)
- [Core Components](#page-components)
- [Hybrid Search & Retrieval](#page-hybrid-search)
- [Knowledge Graph & Entity Management](#page-knowledge-graph)
- [Governance & Safety](#page-governance)
- [Block Format & Data Model](#page-data-model)
- [MCP Server & Tools](#page-mcp-server)
## Overview
### 相关页面
相关主题：[System Architecture](#page-architecture), [Quick Start Guide](#page-quickstart), [MCP Server & Tools](#page-mcp-server)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mind_mem/mm_cli.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)
- [src/mind_mem/mcp/tools/kernels.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/kernels.py)
- [src/mind_mem/mcp/tools/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)
- [src/mind_mem/mcp/tools/memory_ops.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/memory_ops.py)
- [src/mind_mem/mcp/tools/audit.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/audit.py)
- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)
- [src/mind_mem/hook_installer.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hook_installer.py)
- [src/mind_mem/protection.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/protection.py)
# 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
资料来源：[src/mind_mem/compiled_truth.py:1-30]()
## Architecture Overview
The system consists of several interconnected layers:
```mermaid
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
```
资料来源：[src/mind_mem/mm_cli.py:1-25]()
## Workspace Structure
Each workspace managed by MIND-Mem follows a canonical directory layout:
| Directory | Purpose |
|-----------|---------|
| `memory/` | Individual memory blocks as markdown files |
| `entities/` | Entity definitions and compiled truth pages |
| `compiled/` | Compiled truth pages (`entities/compiled/`) |
| `.mind/` | MIND kernel configuration files |
| `signals/` | Staged governance proposals |
| `snapshots/` | Pre-apply rollback snapshots |
资料来源：[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
| Domain | Tools | Purpose |
|--------|-------|---------|
| **Governance** | `propose_update`, `approve_apply`, `rollback_proposal`, `scan`, `list_contradictions`, `memory_evolution` | Memory modification workflow |
| **Memory Ops** | `index_stats`, `reindex`, `delete_memory_item`, `export_memory`, `get_block`, `memory_health`, `compact`, `stale_blocks` | Workspace lifecycle |
| **Kernels** | `list_mind_kernels`, `get_mind_kernel`, `compiled_truth_load`, `compiled_truth_add_evidence`, `compiled_truth_contradictions` | Kernel configuration access |
| **Audit** | `verify_merkle`, `verify_chain`, `list_evidence`, `mind_mem_verify` | Integrity verification |
| **Benchmark** | `governance_health_bench`, `category_summary` | Health diagnostics |
资料来源：[src/mind_mem/mcp/tools/governance.py:1-30]()
### MCP Resources
The server also exposes read-only resources via the MCP resource protocol:
| Resource URI | Content |
|--------------|---------|
| `mind-mem://decisions` | Active decisions from DECISIONS.md |
| `mind-mem://tasks` | All tasks from TASKS.md |
| `mind-mem://entities/{type}` | Projects, people, tools, incidents |
| `mind-mem://signals` | Auto-captured signals |
| `mind-mem://contradictions` | Detected contradictions |
| `mind-mem://health` | Workspace health summary |
| `mind-mem://recall/{query}` | BM25 recall search results |
| `mind-mem://ledger` | Shared multi-agent fact ledger |
资料来源：[src/mind_mem/mcp/resources.py:1-40]()
## CLI Interface
The `mm` command provides a unified interface for non-MCP agents:
```bash
mm recall "" # Search memory with BM25
mm context "" # Generate token-budgeted snippet
mm inject --agent "" # Render snippet for specific agent
mm vault scan # List parsed vault blocks (JSON)
mm vault write --type --body
mm status # Workspace summary
```
资料来源：[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:
```mermaid
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
资料来源：[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:
```mermaid
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
资料来源：[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
资料来源：[src/mind_mem/protection.py:35-60]()
### Audit Chain
| Verification Type | Description |
|-------------------|-------------|
| **Merkle Proofs** | Prove block inclusion against live Merkle tree |
| **Hash Chain** | SHA3-512 chain verification for governance records |
| **Evidence Chain** | Walk and verify evidence relationships |
| **Manifest Signing** | Ed25519 signatures on model audit checkpoints |
资料来源：[src/mind_mem/mcp/tools/audit.py:1-30]()
## Agent Integration
MIND-Mem supports integration with various AI coding assistants through a declarative registry:
| Agent | Config Format | Status |
|-------|---------------|--------|
| Claude | JSON/CLaude Desktop | Configurable |
| Cursor | Custom config | Hook-based |
| Windsurf | Custom config | Hook-based |
| Codex CLI | MCP native | Supported |
The hook installer resolves the MCP server path through:
1. `MIND_MEM_MCP_SERVER` environment variable (explicit override)
2. `/../mcp_server.py` (src-layout checkout)
3. `/mcp_server.py` (packaged install)
资料来源：[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:
| Group | Features |
|-------|----------|
| **A. Cognition** | Tier-aware blocks, Cognitive Mind Kernel API, surprise-weighted retrieval |
| **B. Knowledge Graph** | Block kinds, long-context recall, LLM fusion, streaming, conversational chat |
| **C. Governance UX** | Idle ingest, AI lint, contradiction states, self-healing index |
Without the feature flag, v3.x behavior is preserved unchanged.
资料来源：[src/mind_mem/v4/__init__.py:1-40]()
## Web Console
A Next.js web interface provides visual exploration:
```mermaid
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
资料来源：[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`)
```python
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:
```python
{
"command": "python3",
"args": ["mcp_server.py"],
"env": {"MIND_MEM_WORKSPACE": workspace}
}
```
资料来源：[src/mind_mem/hook_installer.py:50-70]()
## Quick Start
```bash
# 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
```
资料来源：[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
---
## Key Concepts
### 相关页面
相关主题：[Overview](#page-overview), [Block Format & Data Model](#page-data-model), [Governance & Safety](#page-governance)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/block-format.md](https://github.com/star-ga/mind-mem/blob/main/docs/block-format.md)
- [docs/mic-map.md](https://github.com/star-ga/mind-mem/blob/main/docs/mic-map.md)
- [src/mind_mem/block_store.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py)
- [src/mind_mem/namespaces.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/namespaces.py)
- [src/mind_mem/mcp/infra/acl.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/infra/acl.py)
# 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.
---
## Block Format
### Overview
Blocks are the fundamental storage unit in Mind-Mem. Each block represents a discrete unit of knowledge—a decision, task, signal, fact, or entity record—stored as structured Markdown with a consistent header format.
```mermaid
graph LR
A[Block Header
[ID]] --> B[Field: Value]
B --> C[Field: Value]
C --> D[Blank Line]
D --> E[Optional Body
Content]
E --> F[Block Separator
---]
```
资料来源：[src/mind_mem/block_store.py:1-50]()
### Block Header Structure
Every block begins with a unique identifier in the format `[block-id]`:
```
[Dcision-2024-001]
Statement: PostgreSQL shall be the primary relational store
Date: 2024-01-15
Status: Active
Type: Decision
Rationale: Proven reliability and extensive tooling ecosystem
Confidence: high
Tags: infrastructure, database, postgresql
```
资料来源：[docs/block-format.md:1-30]()
### Canonical Field Order
Blocks emit fields in a fixed order to ensure deterministic round-trips:
| Order | Field | Description |
|-------|-------|-------------|
| 1 | `Statement` | Core claim or action |
| 2 | `Date` | ISO-8601 timestamp |
| 3 | `Status` | Active, Superseded, Deprecated |
| 4 | `Priority` | High, Medium, Low |
| 5 | `Risk` | Risk assessment level |
| 6 | `Type` | Decision, Task, Signal, Fact, Entity |
| 7 | `Subject` | Primary entity of interest |
| 8 | `Object` | Secondary entity or target |
| 9 | `Tags` | Comma-separated labels |
| 10 | `Rationale` | Explanation or justification |
| 11 | `Evidence` | Supporting data or references |
| 12 | `Source` | Origin of the information |
| 13 | `Confidence` | low, medium, high |
| 14 | `ContentHash` | SHA-256 content fingerprint |
| 15 | `Excerpt` | Brief summary |
| 16 | `Action` | Next step or task |
资料来源：[src/mind_mem/block_store.py:180-200]()
### Block Types and Prefixes
Mind-Mem uses a prefix-based mapping system to organize blocks into subdirectories:
| Block Type | Prefix | Storage Path |
|------------|--------|--------------|
| Decision | `D` | `decisions/` |
| Task | `T` | `tasks/` |
| Signal | `S` | `signals/` |
| Fact | `F` | `facts/` |
| Entity | `E` | `entities/` |
| Note | `N` | `notes/` |
| Project | `P` | `projects/` |
资料来源：[src/mind_mem/block_store.py:160-175]()
### Forbidden Write Fields
The following synthetic fields are emitted during parsing but are never persisted back to storage:
- `_id` — synthetic parse-time block identifier
- `_source_file` — tool-side hint for source tracking
- `_line_number` — original file location
- `_raw` — unprocessed block content
资料来源：[src/mind_mem/block_store.py:201-205]()
---
## Namespaces
### Overview
Namespaces provide logical isolation between different workspaces, tenants, or organizational units within Mind-Mem. They ensure that blocks and their associated metadata remain segregated while sharing common infrastructure.
```mermaid
graph TD
subgraph Workspace1
NS1[namespace: default]
B1[Block Store]
NS1 --> B1
end
subgraph Workspace2
NS2[namespace: project-a]
B2[Block Store]
NS2 --> B2
end
subgraph Shared
ACL[Access Control List]
Meta[Metadata Index]
end
NS1 --> ACL
NS2 --> ACL
```
资料来源：[src/mind_mem/namespaces.py:1-40]()
### Namespace Resolution
Namespaces are resolved in the following priority order:
1. Explicit `namespace` parameter in API calls
2. `MIND_MEM_NAMESPACE` environment variable
3. Workspace-specific configuration in `mind-mem.json`
4. Default namespace (`default`)
```python
def resolve_namespace(workspace: str, explicit: Optional[str] = None) -> str:
if explicit:
return explicit
env_namespace = os.environ.get("MIND_MEM_NAMESPACE")
if env_namespace:
return env_namespace
config = load_workspace_config(workspace)
return config.get("namespace", "default")
```
资料来源：[src/mind_mem/namespaces.py:45-60]()
### Namespace-Qualified Identifiers
Block IDs can be namespace-qualified using the format `:`:
```
project-a:Dcision-2024-001
default:Task-2024-015
team-infra:Fact-2024-003
```
资料来源：[src/mind_mem/namespaces.py:70-85]()
---
## Access Control Lists (ACL)
### Overview
Mind-Mem implements a declarative ACL system that governs read and write access to blocks based on requester identity, namespace, and operation type.
```mermaid
graph LR
A[Request] --> B[ACL Engine]
B --> C{Namespace Match?}
C -->|Yes| D{Operation Allowed?}
C -->|No| E[Deny: Unknown Namespace]
D -->|Yes| F[Allow]
D -->|No| G[Deny: Permission Denied]
```
资料来源：[src/mind_mem/mcp/infra/acl.py:1-50]()
### ACL Entry Structure
Each ACL entry defines a permission rule:
```json
{
"subject": "agent:cody",
"namespace": "project-a",
"permissions": ["read", "write"],
"conditions": {
"block_types": ["decision", "task", "signal"],
"max_age_days": 30
}
}
```
资料来源：[src/mind_mem/mcp/infra/acl.py:55-70]()
### Permission Types
| Permission | Description | Applicable Operations |
|------------|-------------|----------------------|
| `read` | View block content | `get_block`, `recall`, `search` |
| `write` | Create or modify blocks | `create_block`, `update_block` |
| `delete` | Remove blocks | `delete_block`, `archive_block` |
| `govern` | Approve/reject proposals | `approve_apply`, `rollback` |
| `admin` | Full namespace control | `scan`, `audit`, `reconcile` |
资料来源：[src/mind_mem/mcp/infra/acl.py:75-90]()
### Built-in Roles
Mind-Mem ships with predefined roles for common use cases:
| Role | Permissions | Use Case |
|------|-------------|----------|
| `viewer` | read | Read-only dashboards, reports |
| `contributor` | read, write | Standard agents adding knowledge |
| `governor` | read, write, govern | Governance workflow participants |
| `admin` | read, write, delete, govern, admin | Full workspace management |
资料来源：[src/mind_mem/mcp/infra/acl.py:95-110]()
### ACL Evaluation Logic
```python
def evaluate_acl(request: RequestContext) -> AccessDecision:
# 1. Check for wildcard (allow all)
if _has_wildcard_entry(request.namespace, request.subject):
return AccessDecision(allowed=True, reason="wildcard_match")
# 2. Check explicit deny entries
for entry in _deny_entries(request.namespace, request.subject):
if _matches_conditions(request, entry.conditions):
return AccessDecision(allowed=False, reason="explicit_deny")
# 3. Check explicit allow entries
for entry in _allow_entries(request.namespace, request.subject):
if request.operation in entry.permissions:
if _matches_conditions(request, entry.conditions):
return AccessDecision(allowed=True, reason="explicit_allow")
# 4. Default: deny
return AccessDecision(allowed=False, reason="default_deny")
```
资料来源：[src/mind_mem/mcp/infra/acl.py:120-150]()
---
## Block Storage Architecture
### Directory Structure
Mind-Mem organizes blocks hierarchically under the workspace root:
```
workspace/
├── CLAUDE.md
├── mind-mem.json
├── decisions/
│ └── D-*.md
├── tasks/
│ └── T-*.md
├── signals/
│ └── S-*.md
├── facts/
│ └── F-*.md
├── entities/
│ ├── projects/
│ ├── people/
│ └── tools/
├── memory/
│ └── *.md
├── .ledger/
│ └── ledger.db
└── .signals/
└── signals.db
```
资料来源：[src/mind_mem/block_store.py:50-100]()
### Block Lifecycle
```mermaid
stateDiagram-v2
[*] --> Draft: create_block
Draft --> Active: approve_apply
Active --> Superseded: newer version
Active --> Deprecated: manual
Active --> Archived: delete_block
Draft --> Rejected: governance_reject
Superseded --> Archived: cleanup
Deprecated --> [*]
Archived --> Recoverable: restore_block
```
资料来源：[src/mind_mem/block_store.py:100-130]()
### Quality Gates
Before storage, blocks pass through a deterministic quality gate:
| Rule | Condition | Default Action |
|------|-----------|----------------|
| `empty` | Whitespace-only content | Log warning |
| `too_short` | Fewer than 32 non-whitespace chars | Log warning |
| `oversize` | Exceeds 64 KiB | Reject (strict) |
| `malformed_utf8` | Contains lone surrogates | Reject (strict) |
| `stopwords_only` | All tokens are stopwords | Log warning |
| `near_duplicate` | Levenshtein similarity ≥ 0.97 | Log warning |
| `injection_marker` | Matches prompt-injection patterns | Reject (strict) |
| `ok` | No rule fired | Accept |
资料来源：[src/mind_mem/quality_gate.py:1-50]()
---
## Recall and Retrieval
### BM25 Search
Mind-Mem uses BM25 (Best Matching 25) for keyword-based retrieval:
```python
def recall(workspace: str, query: str, limit: int = 10, active_only: bool = True):
# 1. Parse all blocks in workspace
blocks = parse_workspace_blocks(workspace, active_only=active_only)
# 2. Build inverted index
index = build_bm25_index(blocks)
# 3. Score and rank results
scores = index.score(query)
# 4. Return top-k results with metadata
return sorted(scores, key=lambda x: x.score, reverse=True)[:limit]
```
资料来源：[src/mind_mem/recall.py:1-40]()
### Compiled Truth Pages
Fact blocks can be aggregated into compiled truth pages that consolidate evidence across multiple sources:
```mermaid
graph LR
A[Evidence A] --> B[Compiled Truth Page]
C[Evidence B] --> B
D[Evidence C] --> B
B --> E[Current Understanding]
B --> F[Evidence Trail]
F --> G[Timestamped Entries]
```
资料来源：[src/mind_mem/compiled_truth.py:1-60]()
---
## Governance Model
### Proposal Workflow
All changes to the knowledge base flow through a governed proposal system:
```mermaid
graph LR
A[propose_update] --> B[Staged in SIGNALS.md]
B --> C[Human Review]
C -->|Approve| D[approve_apply]
C -->|Reject| E[Rollback]
D --> F[Active Block]
E --> G[Discarded]
```
资料来源：[src/mind_mem/mcp/tools/governance.py:1-50]()
### Governance Rules
| Rule | Description |
|------|-------------|
| Immutability | Active blocks cannot be directly modified |
| Audit Trail | Every state change is logged with timestamp and actor |
| Separation | Agents propose; humans approve |
| Rollback | Failed applications can be restored from snapshots |
资料来源：[src/mind_mem/mcp/tools/governance.py:50-80]()
---
## Configuration
### Workspace Configuration (`mind-mem.json`)
```json
{
"namespace": "default",
"quality_gate_mode": "advisory",
"recall_limit": 20,
"mcp_schema_version": "3.2.0",
"acl": {
"default_policy": "allow",
"entries": []
}
}
```
资料来源：[src/mind_mem/infra/constants.py:1-30]()
### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `MIND_MEM_WORKSPACE` | Workspace root directory | Current working directory |
| `MIND_MEM_NAMESPACE` | Override namespace | From config |
| `MIND_MEM_LOG_FILE` | Structured log output path | stderr |
| `MIND_MEM_MCP_SERVER` | Path to MCP server binary | Auto-detected |
资料来源：[src/mind_mem/infra/workspace.py:1-40]()
---
## Related Documentation
- [Block Format Specification](docs/block-format.md)
- [MIC Map Reference](docs/mic-map.md)
- [MCP Tools Documentation](src/mind_mem/mcp/tools/)
- [API Reference](src/mind_mem/api/)
---
## Quick Start Guide
### 相关页面
相关主题：[Overview](#page-overview), [MCP Server & Tools](#page-mcp-server)
相关源码文件
以下源码文件用于生成本页说明：
- [examples/README.md](https://github.com/star-ga/mind-mem/blob/main/examples/README.md)
- [examples/basic_usage.py](https://github.com/star-ga/mind-mem/blob/main/examples/basic_usage.py)
- [src/mind_mem/mm_cli.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)
- [src/mind_mem/hook_installer.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hook_installer.py)
- [web/README.md](https://github.com/star-ga/mind-mem/blob/main/web/README.md)
- [src/mind_mem/mcp/resources.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/resources.py)
# 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.
资料来源：[examples/README.md:1-15]()
## Architecture Overview
```mermaid
graph TD
subgraph "Client Layer"
CLI["mm CLI"]
MCP["MCP Server"]
WEB["Web Console"]
end
subgraph "Core Modules"
RECALL["recall.py
BM25 + Vector Recall"]
COGNITIVE["cognitive_forget.py
Token Budget Packing"]
PARSER["block_parser.py
Markdown Parsing"]
end
subgraph "Storage Layer"
FTS["FTS Index
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.
资料来源：[src/mind_mem/mm_cli.py:1-25]()
## Prerequisites
Before getting started with mind-mem, ensure your environment meets these requirements:
| Requirement | Minimum Version | Notes |
|-------------|-----------------|-------|
| Python | 3.10+ | Required for core package |
| SQLite | 3.35+ | Built-in FTS5 support needed |
| pip | 21.0+ | For package installation |
| Node.js | 18+ | Optional, for web console only |
| pnpm/npm | 8+/16+ | Optional, for web console |
For full feature support including encryption and governance:
- OpenSSL 1.1.1+ (for encryption features)
- watchgod or watchdog (optional, for file watching)
资料来源：[examples/README.md:1-20]()
## Installation
### Standard Installation
Install mind-mem from the repository in development/editable mode:
```bash
pip install -e .
```
This installs the package with all dependencies and makes the `mm` CLI available system-wide.
资料来源：[examples/README.md:12-15]()
### Package Structure
After installation, the following components become available:
| Component | Path | Purpose |
|-----------|------|---------|
| `mm` CLI | Command line | Unified interface for all operations |
| Python API | `mind_mem.*` | Programmatic access to recall, governance |
| MCP Server | `mcp_server.py` | Model Context Protocol integration |
| Hook Installer | `hook_installer.py` | Agent configuration for AI clients |
### Workspace Environment
Mind-mem resolves the workspace directory using this precedence:
```mermaid
graph LR
A["MIND_MEM_WORKSPACE
Environment Variable"] --> B{Set?}
B -->|Yes| C["Use env value"]
B -->|No| D["Current Working
Directory"]
C --> E["Realpath Resolution"]
D --> E
```
Set the workspace explicitly:
```bash
export MIND_MEM_WORKSPACE=/path/to/your/project
```
资料来源：[src/mind_mem/mm_cli.py:35-50]()
## Basic Usage
### Running the First Example
The `basic_usage.py` example demonstrates core functionality:
```bash
python3 examples/basic_usage.py
```
资料来源：[examples/README.md:5-8]()
### Python API Walkthrough
The following demonstrates the fundamental workflow using the Python API:
```python
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:
| Command | Description | Example |
|---------|-------------|---------|
| `mm recall` | Search memory | `mm recall "query"` |
| `mm context` | Generate token-budgeted snippet | `mm context "query"` |
| `mm inject` | Render snippet for specific agent | `mm inject --agent claude "query"` |
| `mm vault` | List/manage vault blocks | `mm vault scan ` |
| `mm status` | Workspace summary | `mm status` |
#### Recall Command
```bash
# 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:
```bash
mm context "redis configuration" --max-tokens 2000
```
资料来源：[src/mind_mem/mm_cli.py:53-80]()
## Agent Integration
Mind-mem supports multiple AI coding assistants through the hook installer system.
### Supported Agents
| Agent | Config Format | Detection Method |
|-------|---------------|------------------|
| Claude Code | JSON | Binary path |
| Cursor | JSON | Binary path |
| Windsurf | JSON | Binary path |
| Aider | YAML | Binary path |
| Copilot | Text block | Always offered |
| Cody | JSON | Binary + config path |
| Qodo | Text block | Config path |
资料来源：[src/mind_mem/hook_installer.py:80-150]()
### Installing Agent Hooks
The hook installer generates configuration files and provides MCP server specifications:
```python
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:
```mermaid
graph TD
A["MIND_MEM_MCP_SERVER
env var"] --> B{File exists?}
B -->|Yes| C["Use override path"]
B -->|No| D["src-layout checkout
../mcp_server.py"]
D --> E{File exists?}
E -->|No| F["Packaged install
../mcp_server.py"]
F --> G{File exists?}
G -->|No| H["Package root
mcp_server.py"]
H --> I["Fallback: mcp_server.py"]
```
资料来源：[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:
```bash
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.
资料来源：[web/README.md:1-35]()
### Configuration
Set the API URL if mind-mem isn't on localhost:8080:
```bash
NEXT_PUBLIC_MIND_MEM_API_URL=http://mind-mem.internal:8080 pnpm dev
```
资料来源：[web/README.md:14-18]()
## MCP Resources
The MCP server exposes read-only resources for AI assistants:
| Resource URI | Content |
|--------------|---------|
| `mind-mem://decisions` | Active decisions (DECISIONS.md) |
| `mind-mem://tasks` | All tasks (TASKS.md) |
| `mind-mem://entities/{type}` | Projects, people, tools, incidents |
| `mind-mem://signals` | Auto-captured signals |
| `mind-mem://contradictions` | Detected contradictions |
| `mind-mem://health` | Workspace health summary |
| `mind-mem://recall/{query}` | BM25 recall search |
| `mind-mem://ledger` | Shared multi-agent fact ledger |
Resources are registered after server construction to avoid circular imports.
资料来源：[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
```
资料来源：[examples/basic_usage.py:1-30]()
## Troubleshooting
### Common Issues
| Issue | Solution |
|-------|----------|
| `mm: command not found` | Reinstall package with `pip install -e .` |
| Empty recall results | Check workspace path and memory/ directory |
| MCP connection fails | Verify MIND_MEM_MCP_SERVER path |
| Import errors | Ensure all dependencies installed with `-e .` |
### Debug Mode
Enable verbose logging by setting:
```bash
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.
---
## System Architecture
### 相关页面
相关主题：[Overview](#page-overview), [Core Components](#page-components), [Hybrid Search & Retrieval](#page-hybrid-search)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mind_mem/mcp/resources.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/resources.py)
- [src/mind_mem/mm_cli.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)
- [src/mind_mem/mcp/tools/kernels.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/kernels.py)
- [src/mind_mem/mcp/tools/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)
- [src/mind_mem/mcp/tools/memory_ops.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/memory_ops.py)
- [src/mind_mem/mcp/tools/arch_mind.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/arch_mind.py)
- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)
- [src/mind_mem/apply_engine.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)
- [src/mind_mem/hook_installer.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hook_installer.py)
- [web/README.md](https://github.com/star-ga/mind-mem/blob/main/web/README.md)
# 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.
资料来源：[src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)
## High-Level Architecture
```mermaid
graph TB
subgraph "Client Layer"
CLI[mm CLI]
MCP[MCP Clients
Claude Code, Codex, Cursor, Windsurf]
WebApp[Web Console]
end
subgraph "Interface Layer"
MM_CLI[mm_cli.py
Non-MCP Interface]
MCPServer[MCP Server
FastMCP]
RestAPI[REST API v1]
end
subgraph "Core Engine"
Recall[recall.py
BM25 + Vector Recall]
Graph[knowledge_graph.py
Entity Relationships]
BlockParser[block_parser.py
Markdown Processing]
ApplyEngine[apply_engine.py
Change Application]
end
subgraph "Governance Layer"
Governance[governance.py
Proposals & Approvals]
CompiledTruth[compiled_truth.py
Truth Aggregation]
AuditChain[audit_chain.py
Integrity Verification]
end
subgraph "Data Layer"
Workspace[(Workspace
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.
资料来源：[src/mind_mem/mm_cli.py:28-32](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)
```mermaid
graph TD
W[(Workspace Root)]
W --> |memory/| M[memory/
DECISIONS.md
TASKS.md
entities/]
W --> |intelligence/| I[intelligence/
applied/ snapshots/]
W --> |signals/| S[signals/
SIGNALS.md]
W --> |.mind/| MK[.mind/
kernel configs/]
W --> |mind-mem.json| CFG[mind-mem.json
Configuration]
```
| Directory | Purpose |
|-----------|---------|
| `memory/` | Primary knowledge base (decisions, tasks, entities) |
| `intelligence/` | Applied changes and snapshots for rollback |
| `signals/` | Staged proposals awaiting governance |
| `.mind/` | Mind kernel configuration files |
| `mind-mem.json` | Workspace configuration |
### Block Parser
The block parser extracts structured information from markdown files, supporting various block types with frontmatter metadata.
资料来源：[src/mind_mem/mcp/tools/governance.py:24-26](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)
| Block Type | Prefix | Description |
|------------|--------|-------------|
| DECISION | `# decision` | Architectural decisions with rationale |
| TASK | `# task` | Actionable items with status tracking |
| PROJECT | `# project` | Entity type for project definitions |
| PERSON | `# person` | Entity type for people |
| TOOL | `# tool` | Entity type for tool configurations |
| INCIDENT | `# incident` | Entity type for incidents |
| SIGNAL | `# signal` | Staged proposals |
| CLAIM | `# claim` | Factual assertions with confidence |
### 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.
资料来源：[src/mind_mem/mm_cli.py:36-43](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)
```mermaid
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
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.
资料来源：[src/mind_mem/mcp/resources.py:1-29](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/resources.py)
### MCP Resources
Resources provide read-only access to workspace data:
| Resource URI | Description |
|--------------|-------------|
| `mind-mem://decisions` | Active decisions from DECISIONS.md |
| `mind-mem://tasks` | All tasks from TASKS.md |
| `mind-mem://entities/{type}` | Projects, people, tools, incidents |
| `mind-mem://signals` | Auto-captured signals |
| `mind-mem://contradictions` | Detected contradictions |
| `mind-mem://health` | Workspace health summary |
| `mind-mem://recall/{query}` | BM25 recall search |
| `mind-mem://ledger` | Shared multi-agent fact ledger |
### MCP Tool Categories
#### Governance Tools
Governance tools manage the propose → approve → apply lifecycle:
资料来源：[src/mind_mem/mcp/tools/governance.py:1-28](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)
| Tool | Purpose |
|------|---------|
| `propose_update` | Stage a new decision or task as a SIGNAL |
| `approve_apply` | Apply a staged proposal (dry-run by default) |
| `rollback_proposal` | Restore workspace from pre-apply snapshot |
| `scan` | Integrity scan (contradictions, drift, pending) |
| `list_contradictions` | Enriched contradiction listing |
| `memory_evolution` | A-MEM metadata for a block |
#### Memory Operations Tools
Memory operations provide lifecycle management:
资料来源：[src/mind_mem/mcp/tools/memory_ops.py:1-30](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/memory_ops.py)
| Tool | Purpose |
|------|---------|
| `index_stats` | FTS5 index state inspection |
| `reindex` | Rebuild the full-text search index |
| `delete_memory_item` | Atomic block removal with recovery log |
| `export_memory` | JSONL dump with configurable metadata |
| `get_block` | Block lookup by ID |
| `memory_health` | Health dashboard |
| `compact` | Workspace compaction |
| `stale_blocks` | Staleness-flag management |
#### Kernel Tools
Kernel tools provide access to mind kernel configuration:
资料来源：[src/mind_mem/mcp/tools/kernels.py:1-27](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/kernels.py)
| Tool | Purpose |
|------|---------|
| `list_mind_kernels` | List available .mind kernel files |
| `get_mind_kernel` | Read a specific kernel configuration |
| `compiled_truth_load` | Load truth page for an entity |
| `compiled_truth_add_evidence` | Add evidence to a truth page |
| `compiled_truth_contradictions` | Check for contradictions |
#### Architecture Mind Tools
Arch-mind tools integrate architecture baseline management:
资料来源：[src/mind_mem/mcp/tools/arch_mind.py:1-40](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/arch_mind.py)
| Tool | Purpose |
|------|---------|
| `arch_baseline` | Initialize arch-mind store with baseline |
| `arch_delta` | Compute (current scan) - (baseline scores) |
| `arch_history` | List events in arch-mind store |
| `arch_check_rules` | Apply rules.mind to a fresh scan |
| `arch_session_start` | Open session evidence node |
| `arch_session_end` | Close session, write delta evidence |
| `arch_metric_explain` | Per-metric breakdown for a fixture |
## Governance Workflow
The governance system ensures all memory modifications follow a controlled process:
```mermaid
graph LR
A[Agent proposes
propose_update] --> B{Signal created
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
for rollback]
G --> H[Changes applied
to workspace]
H --> I[Compiled truth
recompiled]
```
### Compiled Truth System
The compiled truth system aggregates evidence per entity into canonical understanding pages:
资料来源：[src/mind_mem/compiled_truth.py:1-50](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)
```
# entity_id — Compiled Truth
## Current Understanding
- Bullet point summary from evidence
## Evidence Trail
### timestamp [CONF] (source: ...)
Observation text
```
| Field | Description |
|-------|-------------|
| `entity_id` | Unique entity identifier |
| `entity_type` | Type (project, person, tool, incident) |
| `compiled_section` | Bullet-point summary of current understanding |
| `evidence_entries` | List of observations with confidence and timestamp |
| `version` | Incremented on each recompilation |
## Apply Engine
The apply engine handles workspace modifications through the configured BlockStore:
资料来源：[src/mind_mem/apply_engine.py:1-60](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)
```mermaid
graph TD
AE[apply_engine.py] --> BS{BlockStore
mind-mem.json}
BS -->|markdown| MS[MarkdownBlockStore]
BS -->|postgres| PS[PostgresBlockStore]
BS -->|encrypted| ES[EncryptedWrapper]
MS --> WD[(Workspace
Files)]
PS --> PG[(PostgreSQL)]
ES --> PS
AE --> |create_snapshot| Snap
AE --> |restore_snapshot| Rest
AE --> |snapshot_diff| Diff
```
| Backend | Configuration | Use Case |
|---------|---------------|----------|
| MarkdownBlockStore | Default | Standard file-based storage |
| PostgresBlockStore | `block_store.backend: postgres` | Scalable multi-tenant |
| EncryptedWrapper | `passphrase` set | Sensitive data protection |
## CLI Interface
The `mm` CLI provides a unified interface for non-MCP agents:
资料来源：[src/mind_mem/mm_cli.py:1-60](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)
```bash
mm recall "" # Search memory
mm context "" # Generate token-budgeted snippet
mm inject --agent "" # Render snippet for specific agent
mm vault scan # List parsed vault blocks (JSON)
mm vault write --type --body
mm status # Workspace summary
```
## Web Console
The web console provides a visual interface for memory exploration:
资料来源：[web/README.md](https://github.com/star-ga/mind-mem/blob/main/web/README.md)
```mermaid
graph TB
Web[Next.js Console] --> API[lib/api.ts]
API --> Recall[/v1/recall]
API --> Health[/v1/health]
Recall --> |bundle| GV[GraphView
d3-force]
Recall --> |bundle| TV[TimelineView
Chronological]
Recall --> |bundle| FL[FactList
Extracted claims]
```
| Component | Purpose |
|-----------|---------|
| `GraphView.tsx` | Force-directed graph of blocks and cross-references |
| `TimelineView.tsx` | Chronological view of dated events |
| `FactList.tsx` | Extracted claims with confidence levels |
## Agent Integration
The hook installer enables per-agent memory integration:
资料来源：[src/mind_mem/hook_installer.py:1-100](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hook_installer.py)
| Agent | Config Path | Format |
|-------|-------------|--------|
| Claude Code | `~/.claude/projects/*/.claude.md` | Markdown block |
| Copilot | `.github/copilot-instructions.md` | Markdown block |
| Cody | `.cody/config.json` | JSON generic |
| Cursor | `.cursor/rules/*.mdc` | Markdown with frontmatter |
| Windsurf | `.codeium/windsurf/mcp_config.json` | JSON windsurf |
| Aider | `.aider.conf.yml` | YAML block |
## v4.0 Future Architecture
The v4.0 package provides side-by-side scaffolding, gated by feature flags:
资料来源：[src/mind_mem/v4/__init__.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/v4/__init__.py)
| Group | Features |
|-------|----------|
| A. Cognition | Tier-aware blocks, Cognitive Mind Kernel, surprise-weighted retrieval |
| B. Knowledge Graph | Entity/concept extraction, long-context recall, LLM fusion, streaming |
| C. Governance UX | Idle background ingest, AI lint with auto-fix, contradiction state machine |
## Key Design Principles
| Principle | Implementation |
|-----------|-----------------|
| Memory immutability | All changes go through governance workflow |
| Auditability | Every modification has a snapshot and proposal trail |
| Multi-agent safety | File locking and governance prevents conflicts |
| Separation of concerns | Distinct layers for interface, core, governance, and data |
| Extensibility | Plugin architecture via BlockStore and MCP tools |
---
## Core Components
### 相关页面
相关主题：[System Architecture](#page-architecture), [Hybrid Search & Retrieval](#page-hybrid-search), [Governance & Safety](#page-governance)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mind_mem/recall.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/recall.py)
- [src/mind_mem/block_store.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py)
- [src/mind_mem/apply_engine.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)
- [src/mind_mem/conflict_resolver.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/conflict_resolver.py)
- [src/mind_mem/drift_detector.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/drift_detector.py)
- [src/mind_mem/tiered_memory.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/tiered_memory.py)
- [src/mind_mem/mcp/tools/core.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/core.py)
# 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
```mermaid
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:
```python
def recall(workspace, query, limit=10, active_only=True)
```
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `workspace` | `str` | required | Root workspace directory path |
| `query` | `str` | required | Search query string |
| `limit` | `int` | `10` | Maximum number of results to return |
| `active_only` | `bool` | `True` | Filter to only active (non-superseded) blocks |
资料来源：[src/mind_mem/recall.py](https://github.com/star-ga/mind-mem/blob/main/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:
```python
from mind_mem.cognitive_forget import pack_to_budget
results = recall(workspace, query)
context = pack_to_budget(results, token_budget)
```
资料来源：[src/mind_mem/recall.py](https://github.com/star-ga/mind-mem/blob/main/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
```mermaid
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
| Backend | Description | Configuration Key |
|---------|-------------|-------------------|
| `MarkdownBlockStore` | Default, file-based storage | N/A (default) |
| `PostgresBlockStore` | Optional SQL backend | `block_store.backend: "postgres"` |
| `EncryptedBlockStore` | Passphrase-protected wrapper | `block_store.backend: "encrypted"` |
资料来源：[src/mind_mem/block_store.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py)
### Block Deletion and Recovery
The storage layer maintains an append-only deletion log for recovery:
```python
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.
资料来源：[src/mind_mem/block_store.py](https://github.com/star-ga/mind-mem/blob/main/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
```mermaid
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
| Operation | Function | Description |
|-----------|----------|-------------|
| Create | `create_snapshot(ws, ts, files_touched)` | Creates pre-apply snapshot for rollback |
| Restore | `restore_snapshot(ws, snap_dir)` | Restores workspace from snapshot |
| Diff | `snapshot_diff(ws, snap_dir)` | Returns list of files that differ |
The apply engine routes through the configured BlockStore, allowing Postgres-backed deployments to snapshot via SQL instead of on-disk copies.
资料来源：[src/mind_mem/apply_engine.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)
### Block Store Routing
```python
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.
资料来源：[src/mind_mem/apply_engine.py](https://github.com/star-ga/mind-mem/blob/main/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
| Method | Purpose |
|--------|---------|
| `detect_conflicts()` | Identify overlapping block modifications |
| `resolve_conflict()` | Apply resolution strategy and merge evidence |
| `get_conflict_history()` | Retrieve conflict metadata for audit |
资料来源：[src/mind_mem/conflict_resolver.py](https://github.com/star-ga/mind-mem/blob/main/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
```mermaid
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
| Drift Type | Detection Method | Severity |
|------------|------------------|----------|
| Semantic Drift | Factual claim contradiction | High |
| Temporal Drift | Outdated timestamps | Medium |
| Structural Drift | Schema/format changes | Low |
资料来源：[src/mind_mem/drift_detector.py](https://github.com/star-ga/mind-mem/blob/main/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
```mermaid
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
| Tier | Criteria | Eviction Policy |
|------|----------|------------------|
| Hot | Recently accessed, high importance | LRU with importance boost |
| Warm | Moderate access frequency | Threshold-based archiving |
| Cold | Stale, low importance | Compression or deletion after grace period |
The consolidation system uses `ConsolidationConfig` to control the forgetting cycle:
```python
cfg = ConsolidationConfig(
importance_threshold=0.25,
stale_days=14,
archive_after_days=60,
grace_days=30,
)
```
资料来源：[src/mind_mem/tiered_memory.py](https://github.com/star-ga/mind-mem/blob/main/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
| Tool | Function | Description |
|------|----------|-------------|
| `list_mind_kernels` | List kernel configs | Enumerate `.mind` kernel configuration files |
| `get_mind_kernel` | Get kernel config | Retrieve specific kernel configuration |
| `compiled_truth_load` | Load truth page | Load compiled truth for an entity |
| `compiled_truth_add_evidence` | Add evidence | Append evidence to a truth page |
| `compiled_truth_contradictions` | List contradictions | Show detected entity contradictions |
### Kernel Configuration Loading
```python
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.
资料来源：[src/mind_mem/mcp/tools/core.py](https://github.com/star-ga/mind-mem/blob/main/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
| Rule | Condition | Default Action |
|------|-----------|----------------|
| `empty` | Whitespace-only content | Log warning |
| `too_short` | Fewer than 32 non-whitespace chars | Log warning |
| `oversize` | Exceeds 64 KiB | Log warning |
| `malformed_utf8` | Contains lone surrogates | Log warning |
| `stopwords_only` | No semantic content | Log warning |
| `near_duplicate` | Similarity ≥ 0.97 to recent block | Log warning |
| `injection_marker` | Matches prompt-injection pattern | Log warning |
| `ok` | No rule fired | Accept |
Quality gate modes:
| Mode | Behavior |
|------|----------|
| `advisory` (default) | Log warnings, always accept |
| `strict` | Reject blocks that trigger any rule |
Configuration sources (in priority order): `strict=True` keyword argument → `QualityGateConfig(mode="strict")` → `mind-mem.json` setting `quality_gate_mode = "strict"`.
资料来源：[src/mind_mem/quality_gate.py](https://github.com/star-ga/mind-mem/blob/main/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
```markdown
---
entity_id:
entity_type:
last_compiled:
version:
---
# — Compiled Truth
## Current Understanding
## Evidence Trail
### [CONF] (source: )
### [SUPERSEDED] (source: )
```
### Evidence Aggregation
The system reads markdown files from `{workspace}/memory/`, counts sentence-level occurrences, and promotes sentences appearing at least `min_mentions` times as candidates for compiled truth pages.
资料来源：[src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)
## Component Interactions
The following diagram illustrates how core components interact during a typical memory operation:
```mermaid
sequenceDiagram
participant Agent
participant MCP_Tools
participant Apply_Engine
participant Quality_Gate
participant Block_Store
participant Recall
participant Drift_Detector
Agent->>MCP_Tools: propose_update()
MCP_Tools->>Quality_Gate: validate(block)
Quality_Gate-->>Apply_Engine: verdict
Apply_Engine->>Apply_Engine: create_snapshot()
Apply_Engine->>Block_Store: write(block)
Block_Store-->>Apply_Engine: success
Agent->>Recall: recall(query)
Recall-->>Agent: results
Recall->>Drift_Detector: check_drift(results)
Drift_Detector-->>Agent: drift_alerts
```
## CLI Integration
The `mm` CLI provides command-line access to core components for non-MCP agents:
| Command | Component | Description |
|---------|-----------|-------------|
| `mm recall ""` | Recall | Search memory |
| `mm context ""` | Recall + cognitive_forget | Generate token-budgeted snippet |
| `mm inject --agent ""` | Recall | Render snippet for specific agent |
| `mm status` | All | Workspace summary |
资料来源：[src/mind_mem/mm_cli.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)
---
## Hybrid Search & Retrieval
### 相关页面
相关主题：[Knowledge Graph & Entity Management](#page-knowledge-graph), [Core Components](#page-components), [Block Format & Data Model](#page-data-model)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mind_mem/mm_cli.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)
- [src/mind_mem/recall_vector.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/recall_vector.py)
- [src/mind_mem/hybrid_recall.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hybrid_recall.py)
- [src/mind_mem/graph_recall.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/graph_recall.py)
- [src/mind_mem/query_expansion.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/query_expansion.py)
- [src/mind_mem/cross_encoder_reranker.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/cross_encoder_reranker.py)
- [src/mind_mem/intent_router.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/intent_router.py)
- [src/mind_mem/mcp/tools/memory_ops.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/memory_ops.py)
- [src/mind_mem/mcp/resources.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/resources.py)
- [docs/scoring.md](https://github.com/star-ga/mind-mem/blob/main/docs/scoring.md)
# 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
```mermaid
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:**
| Query Pattern | Routing | Rationale |
|---------------|---------|-----------|
| Exact terms / keywords | BM25 primary | Precision-focused |
| Conceptual / semantic | Vector primary | Semantic similarity |
| Entity relationships | Graph primary | Traversal-based |
| Complex / multi-aspect | Hybrid RRF | Combined scoring |
资料来源：[src/mind_mem/intent_router.py](https://github.com/star-ga/mind-mem/blob/main/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:**
```python
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
```
资料来源：[src/mind_mem/mm_cli.py:42-47](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py#L42-L47)
### 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
资料来源：[src/mind_mem/recall_vector.py](https://github.com/star-ga/mind-mem/blob/main/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:**
```mermaid
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.
资料来源：[src/mind_mem/graph_recall.py](https://github.com/star-ga/mind-mem/blob/main/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
资料来源：[src/mind_mem/query_expansion.py](https://github.com/star-ga/mind-mem/blob/main/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
资料来源：[src/mind_mem/hybrid_recall.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hybrid_recall.py)
### Integration with MCP Resources
The MCP (Model Context Protocol) layer exposes recall functionality as resources:
```python
"""mind-mem://recall/{query} — BM25 recall search"""
```
This enables MCP-aware AI clients to request memory context directly through the standardized resource interface.
资料来源：[src/mind_mem/mcp/resources.py](https://github.com/star-ga/mind-mem/blob/main/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:**
```mermaid
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
资料来源：[src/mind_mem/cross_encoder_reranker.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/cross_encoder_reranker.py)
## Scoring System
### Score Composition
The final relevance score combines multiple signals:
| Component | Weight | Source |
|-----------|--------|--------|
| BM25 Score | Variable | FTS5 index |
| Vector Similarity | Variable | Embedding model |
| Graph Proximity | Variable | Co-retrieval graph |
| RRF Score | Fixed formula | Rank fusion |
| Cross-Encoder | High | Trained model |
### 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.
资料来源：[docs/scoring.md](https://github.com/star-ga/mind-mem/blob/main/docs/scoring.md)
## MCP Tools Integration
### Memory Operations Tools
The MCP layer provides programmatic access to recall functionality:
| Tool | Purpose |
|------|---------|
| `index_stats` | FTS5 index state inspection |
| `reindex` | Rebuild search indices |
| `get_block` | Direct block retrieval |
| `memory_health` | Retrieval health dashboard |
资料来源：[src/mind_mem/mcp/tools/memory_ops.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/memory_ops.py)
## CLI Usage
### Recall Command
```bash
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.
```bash
mm context "query" # generate budgeted context
```
资料来源：[src/mind_mem/mm_cli.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)
## Configuration
### Kernel Files
Retrieval behavior is tuned through `.mind` kernel configuration files:
| File | Purpose |
|------|---------|
| `bm25.mind` | BM25 parameters (k1, b) |
| `rrf.mind` | RRF k-value and weights |
| `recall.mind` | General recall settings |
The kernel loader supports hot-reloading for runtime tuning:
```python
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")
```
资料来源：[src/mind_mem/mcp/tools/kernels.py](https://github.com/star-ga/mind-mem/blob/main/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](docs/scoring.md) — Detailed scoring algorithms
- [Walkthrough Module](src/mind_mem/walkthrough.py) — Dependency-ordered retrieval for teaching
- [Quality Gate](src/mind_mem/quality_gate.py) — Block quality filtering before storage
---
## Knowledge Graph & Entity Management
### 相关页面
相关主题：[Hybrid Search & Retrieval](#page-hybrid-search), [Governance & Safety](#page-governance), [Block Format & Data Model](#page-data-model)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mind_mem/knowledge_graph.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/knowledge_graph.py)
- [src/mind_mem/entity_ingest.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/entity_ingest.py)
- [src/mind_mem/causal_graph.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/causal_graph.py)
- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)
- [src/mind_mem/contradiction_detector.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/contradiction_detector.py)
- [src/mind_mem/mcp/tools/graph.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/graph.py)
# 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
资料来源：[src/mind_mem/mcp/tools/graph.py:1-17]()
## Architecture
```mermaid
graph TD
subgraph "Data Layer"
KG[Knowledge Graph
retrieval_graph.db]
CG[Causal Graph
causal_graph.db]
TP[Truth Pages
truth/ directory]
ONT[Ontology
Registry]
end
subgraph "Ingestion Layer"
EI[Entity Ingest]
BD[Block Store]
CD[Contradiction
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:
| Field | Type | Description |
|-------|------|-------------|
| `subject` | str | Source entity identifier |
| `predicate` | str | Relationship type |
| `object` | str | Target entity identifier |
| `confidence` | float | Edge confidence (0.0-1.0) |
| `source_block_id` | str | Block that created this edge |
| `created_at` | str | ISO timestamp of creation |
资料来源：[src/mind_mem/mcp/tools/graph.py:20-45]()
### Predicate Types
The system supports predefined predicate types through the `Predicate` enum:
```python
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"
```
资料来源：[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:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `subject` | str | Yes | - | Source entity identifier |
| `predicate` | str | Yes | - | Relationship type |
| `object` | str | Yes | - | Target entity identifier |
| `source_block_id` | str | Yes | - | Source block ID |
| `confidence` | float | No | 1.0 | Edge confidence (0.0-1.0) |
**Returns:**
```json
{
"_schema_version": "3.2.0",
"subject": "PROJECT-A",
"predicate": "depends_on",
"object": "PROJECT-B",
"confidence": 0.95,
"edge_id": 42
}
```
资料来源：[src/mind_mem/mcp/tools/graph.py:30-80]()
#### `graph_query`
Performs N-hop traversal queries on the knowledge graph.
**Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `subject` | str | No | - | Starting node |
| `predicate` | str | No | - | Filter by predicate type |
| `object` | str | No | - | Target node |
| `hops` | int | No | 1 | Number of hops to traverse |
| `direction` | str | No | "out" | "out", "in", or "both" |
资料来源：[src/mind_mem/mcp/tools/graph.py:80-150]()
#### `graph_stats`
Returns aggregate statistics about the knowledge graph.
**Returns:**
```json
{
"total_edges": 156,
"predicates": {
"depends_on": 45,
"related_to": 67,
"references": 44
},
"unique_subjects": 89,
"unique_objects": 102
}
```
资料来源：[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:
```mermaid
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
```
资料来源：[src/mind_mem/ontology.py]()
### Built-in Entity Types
| Entity Type | Parent | Required Fields | Optional Fields |
|-------------|--------|-----------------|-----------------|
| `ENTITY` | - | (name,) | (description, tags) |
| `PROJECT` | ENTITY | (name, status) | (owner, priority, deadline) |
| `PERSON` | ENTITY | (name,) | (role, email, team) |
| `TOOL` | ENTITY | (name,) | (version, language, category) |
| `INCIDENT` | ENTITY | (title,) | (severity, status, assignee) |
| `TASK` | ENTITY | (title,) | (assignee, priority, due) |
资料来源：[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
资料来源：[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
```mermaid
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
```
资料来源：[src/mind_mem/compiled_truth.py]()
### Evidence Entry Fields
| Field | Type | Description |
|-------|------|-------------|
| `timestamp` | str | ISO 8601 timestamp of evidence |
| `source` | str | Source block ID or filename |
| `observation` | str | The factual claim |
| `confidence` | str | "high", "medium", or "low" |
| `superseded` | bool | Whether this entry is outdated |
资料来源：[src/mind_mem/compiled_truth.py:1-50]()
### Truth Page Format
Truth pages are stored as Markdown with YAML frontmatter:
```yaml
---
entity_id: PROJECT-ALPHA
entity_type: PROJECT
last_compiled: 2024-01-15T10:30:00Z
version: 3
---
# PROJECT-ALPHA — Compiled Truth
## Current Understanding
- Multi-agent orchestration platform
- Version 2.1.0 deployed to production
## Evidence Trail
### 2024-01-15T10:30:00Z [HIGH] (source: BLOCK-20240115-001)
Current stable release supporting concurrent task execution.
### 2024-01-10T08:00:00Z [MEDIUM] (source: BLOCK-20240110-015) ~~SUPERSEDED~~
Original architecture diagram showing single-threaded design.
```
资料来源：[src/mind_mem/compiled_truth.py:60-100]()
### Compiled Truth MCP Tools
#### `compiled_truth_load`
Loads a compiled truth page for an entity.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `entity_id` | str | Yes | The entity identifier |
资料来源：[src/mind_mem/mcp/tools/kernels.py:100-150]()
#### `compiled_truth_add_evidence`
Adds new evidence to an entity's truth page and triggers recompilation.
**Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `entity_id` | str | Yes | - | Entity identifier |
| `entity_type` | str | Yes | - | Entity type |
| `observation` | str | Yes | - | The factual claim |
| `source` | str | Yes | - | Source block ID |
| `confidence` | str | No | "medium" | Confidence level |
**Returns:**
```json
{
"_schema_version": "3.2.0",
"entity_id": "PROJECT-ALPHA",
"version": 4,
"evidence_count": 15,
"path": "/workspace/truth/PROJECT-ALPHA.md",
"message": "Evidence added and page recompiled (v4)."
}
```
资料来源：[src/mind_mem/mcp/tools/kernels.py:150-220]()
#### `compiled_truth_contradictions`
Detects contradictions within a compiled truth page.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `entity_id` | str | Yes | Entity identifier |
资料来源：[src/mind_mem/mcp/tools/kernels.py:220-280]()
### Recompilation Process
The `recompile_truth` function regenerates the compiled section from non-superseded evidence:
1. Filters out superseded evidence entries
2. Orders remaining entries by timestamp (newest first)
3. Generates bullet-point summary
4. Increments version number
5. Updates `last_compiled` timestamp
资料来源：[src/mind_mem/compiled_truth.py:200-250]()
## Causal Graph
The causal graph tracks dependency relationships between blocks for impact analysis:
```mermaid
graph LR
A[Decision Made] --> B[Task Created]
B --> C[Implementation Started]
A --> D[Risk Assessment]
C --> E[Code Reviewed]
D --> F[Mitigation Applied]
E --> G[Deployed]
F --> G
```
### Traversal for Impact Analysis
The `traverse_graph` function supports:
- **Forward propagation**: "What blocks depend on this?"
- **Backward propagation**: "What blocks does this depend on?"
- **Reachability queries**: "Are these blocks connected?"
- **Critical path identification**: Longest dependency chains
资料来源：[src/mind_mem/causal_graph.py]()
## Contradiction Detection
### Detection Strategy
The contradiction detector analyzes evidence entries to identify conflicting claims:
1. **Temporal conflict**: Claims that cannot both be true given their timestamps
2. **Semantic conflict**: Claims with opposing sentiment or meaning
3. **Logical conflict**: Claims that logically exclude each other based on domain rules
### Detection Function
```python
def detect_contradictions(page: CompiledTruthPage) -> list[Contradiction]:
"""Detect contradictions in a compiled truth page.
Returns a list of detected contradictions with severity and
affected evidence indices.
"""
```
资料来源：[src/mind_mem/contradiction_detector.py]()
### Contradiction Resolution
When contradictions are detected, the system supports:
1. **Supersession**: Mark older evidence as `superseded=True`
2. **Escalation**: Flag for human review through the governance workflow
3. **Version branching**: Create alternative truth pages for competing hypotheses
资料来源：[src/mind_mem/compiled_truth.py:180-200]()
## MCP Tool Summary
| Tool | Domain | Purpose |
|------|--------|---------|
| `graph_add_edge` | Knowledge Graph | Add typed relationship |
| `graph_query` | Knowledge Graph | N-hop traversal queries |
| `graph_stats` | Knowledge Graph | Graph statistics |
| `traverse_graph` | Causal Graph | Dependency impact analysis |
| `compiled_truth_load` | Truth Pages | Load entity truth page |
| `compiled_truth_add_evidence` | Truth Pages | Add evidence and recompile |
| `compiled_truth_contradictions` | Truth Pages | Detect conflicts |
| `list_contradictions` | Governance | List all contradictions |
| `memory_evolution` | Governance | A-MEM block metadata |
资料来源：[src/mind_mem/mcp/tools/graph.py](), [src/mind_mem/mcp/tools/kernels.py](), [src/mind_mem/mcp/tools/governance.py]()
## Configuration
### Workspace Configuration
In `mind-mem.json`:
```json
{
"knowledge_graph": {
"enabled": true,
"db_path": "intelligence/state/retrieval_graph.db"
},
"causal_graph": {
"enabled": true,
"db_path": "intelligence/state/causal_graph.db"
},
"truth_pages": {
"enabled": true,
"directory": "truth/"
},
"contradiction_detection": {
"enabled": true,
"severity_threshold": "medium"
}
}
```
### Schema Version
All MCP tools return responses with `_schema_version` for API compatibility:
```python
MCP_SCHEMA_VERSION = "3.2.0"
```
资料来源：[src/mind_mem/infra/constants.py]()
---
## Governance & Safety
### 相关页面
相关主题：[Core Components](#page-components), [Key Concepts](#page-key-concepts), [Block Format & Data Model](#page-data-model)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mind_mem/governance_gate.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/governance_gate.py)
- [src/mind_mem/contradiction_detector.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/contradiction_detector.py)
- [src/mind_mem/drift_detector.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/drift_detector.py)
- [src/mind_mem/audit_chain.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/audit_chain.py)
- [src/mind_mem/quality_gate.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/quality_gate.py)
- [src/mind_mem/abstention_classifier.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/abstention_classifier.py)
- [mind/governance.mind](https://github.com/star-ga/mind-mem/blob/main/mind/governance.mind)
- [docs/governance.md](https://github.com/star-ga/mind-mem/blob/main/docs/governance.md)
- [docs/protection.md](https://github.com/star-ga/mind-mem/blob/main/docs/protection.md)
# 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:
```mermaid
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
```
资料来源：[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
资料来源：[src/mind_mem/mcp/tools/governance.py:17-20]()
### Governance Workflow States
```mermaid
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.
资料来源：[src/mind_mem/quality_gate.py:1-20]()
### Quality Rules
| Rule ID | Rule Name | Description | Default Action |
|---------|-----------|-------------|----------------|
| 1 | `empty` | Block is whitespace-only | Log only |
| 2 | `too_short` | Fewer than 32 non-whitespace characters | Log only |
| 3 | `oversize` | Exceeds 64 KiB of UTF-8 bytes | Log only |
| 4 | `malformed_utf8` | Contains lone surrogates or cannot round-trip | Log only |
| 5 | `stopwords_only` | Every token is a stopword (no semantic content) | Log only |
| 6 | `near_duplicate` | Levenshtein similarity ≥ 0.97 to a recent block (within 24h) | Log only |
| 7 | `injection_marker` | Matches a known prompt-injection pattern | Log only |
| 8 | `ok` | No rule fired (happy path) | Accept |
### Quality Gate Modes
The quality gate operates in two modes:
| Mode | Behavior | Trigger |
|------|----------|---------|
| **Advisory** (default) | All rules logged but verdict still `accept` | Default configuration |
| **Strict** | Any rule that fires causes `reject` | `strict=True` kwarg OR `QualityGateConfig(mode="strict")` OR `mind-mem.json` setting |
资料来源：[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.
资料来源：[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
```python
@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
```python
@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
```mermaid
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
| Function | Purpose |
|----------|---------|
| `load_truth_page(workspace, entity_id)` | Load compiled truth from `{workspace}/entities/compiled/{entity_id}.md` |
| `save_truth_page(workspace, page)` | Persist truth page to disk |
| `recompile_truth(page)` | Regenerate compiled section from non-superseded evidence |
| `supersede_evidence(page, entry_index, reason)` | Mark an evidence entry as superseded |
| `detect_contradictions(page)` | Scan for conflicting evidence entries |
资料来源：[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
```python
@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
```
资料来源：[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
| Category | Description |
|----------|-------------|
| **Content Drift** | Gradual semantic shifts in memory content |
| **Structural Drift** | Changes in block format or organization |
| **Behavioral Drift** | Patterns in how memory is modified |
| **Governance Drift** | Deviation from governance-approved workflows |
资料来源：[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
```mermaid
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
| Tool | Purpose |
|------|---------|
| `verify_merkle(block_id, content_hash)` | Prove a block's Merkle inclusion against the live tree |
| `verify_chain()` | Walk both SHA3-512 governance hash chain and evidence chain |
| `list_evidence(block_id, action)` | Enumerate governance evidence objects with filters |
资料来源：[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.
资料来源：[src/mind_mem/mcp/tools/governance.py:1-25]()
### Tool Reference
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `propose_update` | Stage a new decision/task as a SIGNAL | `block_type`, `statement`, `rationale`, `tags`, `confidence` |
| `approve_apply` | Apply a staged proposal (dry-run by default) | `signal_id`, `dry_run` |
| `rollback_proposal` | Restore workspace from pre-apply snapshot | `signal_id` |
| `scan` | Integrity scan (contradictions/drift/pending) | — |
| `list_contradictions` | Enriched contradiction listing | `entity_id` (optional) |
| `memory_evolution` | A-MEM metadata for a block | `block_id` |
### `propose_update` Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `block_type` | `str` | required | Decision or task |
| `statement` | `str` | required | The proposed content |
| `rationale` | `str` | "" | Justification |
| `tags` | `str` | "" | Comma-separated tags |
| `confidence` | `str` | "medium" | low/medium/high |
### `approve_apply` Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `signal_id` | `str` | required | Signal identifier to apply |
| `dry_run` | `bool` | `true` | Preview without applying |
### `rollback_proposal` Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `signal_id` | `str` | required | Signal to rollback |
资料来源：[src/mind_mem/mcp/tools/governance.py:30-100]()
## Governance Health Benchmark
The governance health benchmark (`governance_health_bench`) exercises the full governance system:
```mermaid
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
| Sub-Suite | Description |
|-----------|-------------|
| Contradiction Detection | Tests contradiction detector against known conflict patterns |
| Audit Completeness | Verifies all governance actions have audit records |
| Drift Detection | Exercises drift detection with synthetic drift scenarios |
| Scalability Probes | Performance testing under load |
资料来源：[src/mind_mem/mcp/tools/benchmark.py:1-40]()
## Configuration
### Workspace Configuration
The governance system respects workspace-level configuration in `mind-mem.json`:
```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:
| Kernel File | Purpose |
|-------------|---------|
| `governance.mind` | Governance rules and workflow configuration |
| `contradictions.mind` | Contradiction detection parameters |
| `protection.mind` | Safety thresholds and limits |
资料来源：[mind/governance.mind:1-30]()
## MCP Resources
Governance state is also exposed as read-only MCP resources:
| Resource URI | Description |
|--------------|-------------|
| `mind-mem://contradictions` | Detected contradictions |
| `mind-mem://health` | Workspace health summary |
| `mind-mem://ledger` | Shared multi-agent fact ledger |
资料来源：[src/mind_mem/mcp/resources.py:1-40]()
## Error Handling
### Structured Error Envelope
All governance tools return a consistent error format:
```json
{
"_schema_version": "3.2.0",
"error": "Human-readable error message"
}
```
### Common Error Scenarios
| Scenario | Error Message Pattern |
|----------|----------------------|
| Entity not found | "No compiled truth page found for '{entity_id}'" |
| Failed evidence add | "Failed to add evidence: {exception}" |
| Rollback unavailable | "No snapshot found for signal '{signal_id}'" |
| Workspace locked | SQLite busy error (retry-able) |
资料来源：[src/mind_mem/mcp/tools/kernels.py:60-80]()
## Metrics and Observability
Governance operations emit metrics for monitoring:
| Metric Name | Description |
|-------------|-------------|
| `mcp_kernel_list` | Kernel list operations |
| `mcp_compiled_truth_add_evidence` | Evidence additions |
| `evidence_entries_superseded` | Superseded evidence count |
| `truth_pages_loaded` | Truth page load operations |
| `contradictions_detected` | New contradictions found |
资料来源：[src/mind_mem/mcp/tools/kernels.py:35-40]()
## See Also
- [Memory System](./memory-system.md) — Core memory storage and retrieval
- [MCP Tools](./mcp-tools.md) — MCP tool reference
- [CLI Reference](./cli-reference.md) — `mm` command-line interface
- [Protection](./protection.md) — Safety mechanisms and thresholds
---
## Block Format & Data Model
### 相关页面
相关主题：[Key Concepts](#page-key-concepts), [Hybrid Search & Retrieval](#page-hybrid-search)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)
- [src/mind_mem/block_store.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py)
- [src/mind_mem/block_parser.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_parser.py)
- [src/mind_mem/schema_version.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/schema_version.py)
- [src/mind_mem/mcp/tools/kernels.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/kernels.py)
# 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.
资料来源：[src/mind_mem/block_store.py:1-50]()
## Block Structure
### Anatomy of a Block
A mind-mem block consists of three main parts:
```markdown
[UNIQUE_BLOCK_ID]
Field1: value
Field2: value
ListField:
- item1
- item2
Tags: tag1, tag2
---
```
| Component | Description | Example |
|-----------|-------------|---------|
| Block ID | Unique identifier in square brackets | `[DECISION-2024-001]` |
| Fields | Key-value pairs with colon separators | `Status: active` |
| Separator | `---` marks block end | `---` |
资料来源：[src/mind_mem/block_store.py:45-75]()
### Canonical Field Order
Blocks emit fields in a fixed order to ensure deterministic round-trips. Unknown fields are appended alphabetically after the canonical head.
```python
_CANONICAL_FIELD_ORDER: tuple[str, ...] = (
"Statement",
"Date",
"Status",
"Priority",
"Risk",
"Type",
"Subject",
"Object",
"Tags",
"Rationale",
"Evidence",
"Source",
"Confidence",
"ContentHash",
"Excerpt",
"Action",
)
```
资料来源：[src/mind_mem/block_store.py:28-46]()
### Forbidden Write Fields
These internal fields are parsed for display but never written back to storage:
```python
_FORBIDDEN_WRITE_FIELDS: frozenset[str] = frozenset({
"_id",
"_source_file",
"_line_number",
"_raw"
})
```
资料来源：[src/mind_mem/block_store.py:48]()
## Block Storage Architecture
### Directory Organization
Blocks are stored across multiple directories based on their type prefix:
```mermaid
graph TD
A["Block ID: `[DECISION-xxx]`"] --> B["_BLOCK_PREFIX_MAP"]
B --> C["`decisions/` directory"]
A2["Block ID: `[TASK-xxx]`"] --> B
B --> C2["`tasks/` directory"]
A3["Block ID: `[PROJECT-xxx]`"] --> B
B --> C3["`projects/` directory"]
A4["Block ID: `[INCIDENT-xxx]`"] --> B
B --> C4["`incidents/` directory"]
```
### Block Prefix Mapping
The system maps block ID prefixes to their canonical storage locations:
| Prefix | Storage Directory | Description |
|--------|-------------------|-------------|
| `DECISION` | `decisions/` | Decision records |
| `TASK` | `tasks/` | Task items |
| `PROJECT` | `projects/` | Project definitions |
| `INCIDENT` | `incidents/` | Incident reports |
| `PERSON` | `people/` | Person entities |
| `TOOL` | `tools/` | Tool definitions |
| `SIGNAL` | `signals/` | Auto-captured signals |
资料来源：[src/mind_mem/block_store.py:15-26]()
## Block Rendering
### Serialization Process
The `_render_block()` function converts a parsed block dictionary back to its Markdown form:
```mermaid
graph LR
A["block dict"] --> B["Extract _id"]
B --> C["Lookup target file"]
C --> D["Render fields in canonical order"]
D --> E["Handle list fields as bullets"]
E --> F["Neutralize \\n[ to prevent block collision"]
F --> G["Output markdown string"]
```
Key rendering rules:
- Lists are rendered as `- item` bullets on lines following the field
- Multi-line values are emitted verbatim
- Newline-plus-left-bracket sequences are neutralized to prevent accidental block headers
资料来源：[src/mind_mem/block_store.py:50-85]()
### Write Surface
The `BlockStore.write_block()` method handles persistence:
```python
def write_block(self, block: dict[str, Any]) -> str:
block_id = block.get("_id")
target = _resolve_block_file(self._workspace, block_id)
rendered = _render_block(block)
with FileLock(target):
# Replace existing or append
existing_text = fh.read()
loc = _locate_block_in_text(existing_text, block_id)
# Insert or append
```
资料来源：[src/mind_mem/block_store.py:120-160]()
## Compiled Truth Pages
### Purpose
Compiled Truth Pages aggregate evidence for a specific entity into a canonical understanding. They maintain an **evidence trail** showing how knowledge evolved over time.
```mermaid
graph TD
A["Evidence Entries
from memory/"] --> B["Compile Process"]
B --> C["CompiledTruthPage"]
C --> D["Current Understanding"]
C --> E["Evidence Trail"]
```
### Data Model
```python
class CompiledTruthPage:
entity_id: str
entity_type: str
compiled_section: str # Canonical understanding
evidence_entries: list[EvidenceEntry]
last_compiled: datetime
version: str
class EvidenceEntry:
timestamp: str
source: str
observation: str
confidence: str # HIGH, MEDIUM, LOW
superseded: bool # Marked if later evidence contradicts
```
资料来源：[src/mind_mem/compiled_truth.py:20-50]()
### Markdown Format
Compiled Truth Pages use structured Markdown with YAML frontmatter:
```markdown
---
entity_id: postgresql-migration
entity_type: project
last_compiled: 2024-01-15T10:30:00Z
version: v3
---
# postgresql-migration — Compiled Truth
## Current Understanding
The migration to PostgreSQL 16 is complete and stable.
## Evidence Trail
### 2024-01-10 [HIGH] (source: decisions.md)
Initial decision to migrate from MySQL to PostgreSQL.
### 2024-01-12 [MEDIUM] (source: signals.md) ~~SUPERSEDED~~
Interim report showing migration issues. ~~SUPERSEDED~~
```
资料来源：[src/mind_mem/compiled_truth.py:55-95]()
### File Operations
| Function | Purpose | Location |
|----------|---------|----------|
| `format_truth_page()` | Serialize page to Markdown | `entities/compiled/{entity_id}.md` |
| `parse_truth_page()` | Parse Markdown back to page object | Read from `entities/compiled/` |
| `load_truth_page()` | Load from disk, return `None` if missing | `entities/compiled/{entity_id}.md` |
| `save_truth_page()` | Persist page to disk | `entities/compiled/{entity_id}.md` |
资料来源：[src/mind_mem/compiled_truth.py:95-150]()
## Block Lifecycle
```mermaid
graph TD
A["Block Created"] --> B["Quality Gate Check"]
B --> C{Pass?}
C -->|No| D["Log verdict
Reject if strict mode"]
C -->|Yes| E["Parse & Validate"]
E --> F["Write to canonical file"]
F --> G["Index for recall"]
G --> H["Block Active"]
H --> I{"Update proposal?"}
I -->|Yes| J["Stage as SIGNAL"]
I -->|No| K["Query via recall API"]
```
### Quality Gate Rules
Before storage, blocks pass through eight deterministic checks:
| Rule | Condition | Default Behavior |
|------|-----------|-------------------|
| `empty` | Whitespace-only content | Accept with log |
| `too_short` | < 32 non-whitespace chars | Accept with log |
| `oversize` | > 64 KiB UTF-8 bytes | Reject |
| `malformed_utf8` | Lone surrogates present | Reject |
| `stopwords_only` | All tokens are stopwords | Accept with log |
| `near_duplicate` | ≥ 0.97 similarity to recent block | Accept with log |
| `injection_marker` | Matches known injection patterns | Reject |
资料来源：[src/mind_mem/quality_gate.py:1-30]()
## Deletion & Recovery
### Block Deletion
When a block is deleted, its content is preserved in a recovery journal:
```python
def _delete_block(self, block_id: str, workspace: str) -> None:
log_path = os.path.join(workspace, "memory", "deleted_blocks.jsonl")
entry = {
"block_id": block_id,
"deleted_at": datetime.now(timezone.utc).isoformat(),
"content": content,
}
with open(log_path, "a") as f:
f.write(json.dumps(entry) + "\n")
```
### Locating Blocks in Text
The `_locate_block_in_text()` function finds block boundaries:
1. Block starts at line exactly equal to `[]`
2. Block ends at:
- Next `[]` header line
- Isolated `---` separator (preceded by blank line)
- End of file
资料来源：[src/mind_mem/block_store.py:100-120]()
## Summary
The mind-mem block format provides:
| Feature | Implementation |
|---------|----------------|
| **Storage** | Markdown files organized by type prefix |
| **Serialization** | Canonical field ordering for deterministic output |
| **Compiled Truth** | Aggregated evidence with version tracking |
| **Recovery** | JSONL deletion log for block restoration |
| **Quality** | Eight-rule pre-storage gate |
| **Concurrency** | File-level locking via `FileLock` |
This design enables human-readable storage, git-friendly versioning, and a flexible recall system that can parse and index blocks across the workspace.
---
## MCP Server & Tools
相关源码文件
以下源码文件用于生成本页说明：
- [src/mind_mem/mcp/resources.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/resources.py)
- [src/mind_mem/mcp/tools/kernels.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/kernels.py)
- [src/mind_mem/mcp/tools/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)
- [src/mind_mem/mcp/tools/memory_ops.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/memory_ops.py)
- [src/mind_mem/mcp/tools/consolidation.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/consolidation.py)
- [src/mind_mem/mcp/tools/core.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/core.py)
- [src/mind_mem/mcp/tools/benchmark.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/benchmark.py)
- [src/mind_mem/mcp/tools/arch_mind.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/arch_mind.py)
- [src/mind_mem/mm_cli.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)
# MCP Server & Tools
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.
```python
# 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. 资料来源：[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
| Resource URI | Source Document | Description |
|-------------|-----------------|-------------|
| `mind-mem://decisions` | `DECISIONS.md` | Active decisions (ADRs) |
| `mind-mem://tasks` | `TASKS.md` | All tracked tasks |
| `mind-mem://entities/{type}` | `memory/entities/*.md` | Projects, people, tools, incidents |
| `mind-mem://signals` | `memory/signals/` | Auto-captured signals |
| `mind-mem://contradictions` | `memory/contradictions/` | Detected contradictions |
| `mind-mem://health` | Computed | Workspace health summary |
| `mind-mem://recall/{query}` | Computed | BM25 recall search results |
| `mind-mem://ledger` | `memory/ledger/` | Shared multi-agent fact ledger |
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. 资料来源：[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.
```python
@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.
| Tool | Purpose |
|------|---------|
| `recall` | Full-text search with configurable backend (BM25, auto, hybrid) |
| `context` | Token-budgeted snippet generation |
| `explain` | Query intent explanation |
| `trace` | MCP call log tail viewer |
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). 资料来源：[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.
| Tool | Purpose |
|------|---------|
| `propose_update` | Stage a new decision or task as a SIGNAL |
| `approve_apply` | Apply a staged proposal (dry-run by default) |
| `rollback_proposal` | Restore workspace from pre-apply snapshot |
| `scan` | Integrity scan for contradictions, drift, and pending items |
| `list_contradictions` | Enriched contradiction listing |
| `memory_evolution` | A-MEM metadata for a block |
### Governance Workflow
```mermaid
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. 资料来源：[src/mind_mem/mcp/tools/governance.py:1-60]()
## Memory Operations Tools
Memory operations tools manage the workspace lifecycle and provide introspection capabilities.
| Tool | Purpose |
|------|---------|
| `index_stats` | FTS5 index state inspection |
| `reindex` | Full index rebuild |
| `delete_memory_item` | Atomic block removal with recovery log |
| `export_memory` | JSONL dump with configurable metadata and size cap |
| `get_block` | Block lookup by ID |
| `memory_health` | Health dashboard |
| `compact` | Workspace compaction |
| `stale_blocks` | Staleness-flag management |
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. 资料来源：[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.
| Tool | Purpose |
|------|---------|
| `list_mind_kernels` | List available kernel configurations |
| `get_mind_kernel` | Retrieve specific kernel configuration |
| `compiled_truth_load` | Load entity truth page |
| `compiled_truth_add_evidence` | Add evidence to truth page |
| `compiled_truth_contradictions` | Detect contradictions in truth page |
These tools interact with the FFI layer (`mind_ffi`) to load and persist kernel configurations stored in the workspace's `.mind/` directory. 资料来源：[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.
| Tool | Purpose |
|------|---------|
| `plan_consolidation` | Dry-run of the cognitive forgetting cycle |
| `propagate_staleness` | Diffusion of staleness scores over cross-references |
| `project_profile` | Structured session-start intelligence summary |
| `dream_cycle` | Autonomous memory 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)
```mermaid
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]
```
资料来源：[src/mind_mem/mcp/tools/consolidation.py:1-60]()
## Benchmark Tools
Benchmark tools provide governance health validation and category analysis.
| Tool | Purpose |
|------|---------|
| `governance_health_bench` | Run contradiction detection, audit completeness, drift, and scalability probes |
| `category_summary` | Category distiller lookup with configurable limits |
The governance health benchmark exercises the full suite of validation checks and returns aggregated pass/fail counts per sub-suite. 资料来源：[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.
| Tool | Purpose |
|------|---------|
| `build_core` | Snapshot blocks and knowledge graph into portable `.mmcore` archive |
| `load_core` | Load a `.mmcore` bundle into workspace |
| `unload_core` | Unload and remove core bundle |
| `list_cores` | List installed cores |
Bundles support namespace prefixing for block isolation when loading cores from different 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.
| Tool | Purpose |
|------|---------|
| `arch_baseline` | Initialize arch-mind store with baseline |
| `arch_delta` | Compute (current scan) - (baseline scores) |
| `arch_history` | List events in arch-mind store |
| `arch_check_rules` | Apply rules.mind to fresh scan |
| `arch_session_start` | Open session evidence node |
| `arch_session_end` | Close session, write delta evidence |
| `arch_metric_explain` | Per-metric breakdown for a fixture |
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. 资料来源：[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
| Command | MCP Equivalent | Description |
|---------|---------------|-------------|
| `mm recall ""` | recall tool | Search memory |
| `mm context ""` | context tool | Generate token-budgeted snippet |
| `mm inject --agent ""` | inject tool | Render snippet for specific agent |
| `mm vault scan ` | vault tools | List parsed vault blocks (JSON) |
| `mm vault write --type --body ` | vault tools | Write vault block |
| `mm status` | memory_health tool | Workspace summary |
| `mm explain` | explain tool | Query intent explanation |
| `mm trace` | trace tool | MCP call log tail |
The workspace is resolved via `MIND_MEM_WORKSPACE` environment variable, defaulting to `cwd` if unset. 资料来源：[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
```python
@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:
```markdown
---
entity_id: project-alpha
entity_type: project
last_compiled: 2026-01-15T10:30:00Z
version: 3
---
# project-alpha — Compiled Truth
## Current Understanding
[Compiled canonical understanding]
## Evidence Trail
### 2026-01-15T10:30:00Z [HIGH] (source: standup-notes.md)
[Observation text]
```
Evidence entries are ordered newest-first, with superseded entries marked for visibility. 资料来源：[src/mind_mem/compiled_truth.py:1-100]()
## Observability & Metrics
All MCP tools are wrapped with `@mcp_tool_observe` for automatic metrics emission. The observability layer tracks:
- Tool invocation counts per tool name
- Error rates and exception types
- Latency percentiles
- Workspace-scoped activity
Tools can optionally use the `@_traced` decorator for detailed request tracing that captures the full call chain. 资料来源：[src/mind_mem/mcp/tools/governance.py:1-50]()
## Agent Integration
The `hook_installer` module provides declarative integration for various AI coding clients:
| Agent | Config Format | Detection |
|-------|--------------|-----------|
| claude | JSON config block | `claude` binary |
| cursor | JSON config block | `cursor` binary |
| windsurf | MCP JSON | `windsurf` binary |
| aider | YAML block | `aider` binary |
| openclaw | JSON hooks | `~/.openclaw/` path |
| copilot | Text block | Always offered |
| cody | JSON generic | `cody` binary |
| qodo | Text block | `~/.codium/` path |
Each agent type has a canonical config file path, content template with the `MIND_MEM_MARKER`, and detection strategy (binary presence, config path, or explicit flag). 资料来源：[src/mind_mem/hook_installer.py:1-200]()
## Configuration
### Environment Variables
| Variable | Purpose | Default |
|----------|---------|---------|
| `MIND_MEM_WORKSPACE` | Workspace root directory | `cwd` |
| `MIND_MEM_MCP_SERVER` | Override MCP server path | Auto-detect |
| `ARCH_MIND_BIN` | arch-mind binary path | `arch-mind` on PATH |
| `MIND_MEM_LOG_FILE` | Structured JSON log path | stderr |
### Workspace Structure
```
workspace/
├── DECISIONS.md # Active decisions
├── TASKS.md # Task tracking
├── memory/
│ ├── entities/ # Entity truth pages
│ ├── signals/ # Auto-captured signals
│ ├── contradictions/ # Detected contradictions
│ ├── ledger/ # Multi-agent fact ledger
│ └── cores/ # .mmcore bundles
└── .mind/ # Kernel configurations
```
## Summary
The MCP Server & Tools layer transforms mind-mem from a library into a first-class AI teammate interface. By exposing all capabilities through the Model Context Protocol:
1. **Recall** becomes a first-class tool with configurable backends and output formats
2. **Governance** enforces change management through propose-apply-rollback workflows
3. **Consolidation** runs autonomously based on configurable importance thresholds
4. **Observability** tracks all tool usage for audit and improvement
The modular tool organization allows clients to consume only the capabilities they need while maintaining a coherent system that enforces invariants like "memory is never modified except by governance."
---
---
## Doramagic 踩坑日志
项目：star-ga/mind-mem
摘要：发现 21 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks)。
## 1. 安装坑 · 来源证据：PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_366d8c18c1aa45ffb07174af516285d4 | https://github.com/star-ga/mind-mem/issues/524 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 2. 安装坑 · 来源证据：PG-backed: `mm recall` returns [] despite direct PG FTS finding matches
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：PG-backed: `mm recall` returns [] despite direct PG FTS finding matches
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ba0bc6a7eec24a3a963611eac1e66e9f | https://github.com/star-ga/mind-mem/issues/525 | 来源类型 github_issue 暴露的待验证使用条件。
## 3. 安装坑 · 来源证据：Perf regression: build_index on a fresh 80KB workspace takes ~55s
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Perf regression: build_index on a fresh 80KB workspace takes ~55s
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_af7792e47f904c0ea9362c21e6944c19 | https://github.com/star-ga/mind-mem/issues/530 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 4. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:1160652179 | https://github.com/star-ga/mind-mem | host_targets=mcp_host, claude, claude_code, cursor
## 5. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1160652179 | https://github.com/star-ga/mind-mem | README/documentation is current enough for a first validation pass.
## 6. 维护坑 · 来源证据：test_rollback_removes_new_files fails on macOS + Windows runners (passes on Linux)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：test_rollback_removes_new_files fails on macOS + Windows runners (passes on Linux)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e1922336b59a45f889940eab33dba770 | https://github.com/star-ga/mind-mem/issues/515 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 7. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1160652179 | https://github.com/star-ga/mind-mem | last_activity_observed missing
## 8. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1160652179 | https://github.com/star-ga/mind-mem | no_demo; severity=medium
## 9. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1160652179 | https://github.com/star-ga/mind-mem | no_demo; severity=medium
## 10. 安全/权限坑 · 来源证据：ACL `_get_request_scope` fail-open on token-introspection exception (acl.py:139-142)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ACL `_get_request_scope` fail-open on token-introspection exception (acl.py:139-142)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_0a6d1439d14f4eb79c2e37a14ed436b0 | https://github.com/star-ga/mind-mem/issues/526 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 11. 安全/权限坑 · 来源证据：FederationClient: no scheme allowlist, no redirect cap, no response-size cap, no TLS pinning (federation_client.py:240-…
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：FederationClient: no scheme allowlist, no redirect cap, no response-size cap, no TLS pinning (federation_client.py:240-251)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_1e9c9207806f46a6a90a83828e99c173 | https://github.com/star-ga/mind-mem/issues/529 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 12. 安全/权限坑 · 来源证据：THREE_WAY_MERGE doesn't bump vclock — resolved conflicts recur on every detect_conflict pass (federation.py:359-360)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：THREE_WAY_MERGE doesn't bump vclock — resolved conflicts recur on every detect_conflict pass (federation.py:359-360)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ea39fdeb939e484a9be8751555483fc5 | https://github.com/star-ga/mind-mem/issues/527 | 来源类型 github_issue 暴露的待验证使用条件。
## 13. 安全/权限坑 · 来源证据：[CRITICAL] N-01 / T-002: Default-on ACL gate (admin tools open with MIND_MEM_ADMIN_TOKEN unset)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[CRITICAL] N-01 / T-002: Default-on ACL gate (admin tools open with MIND_MEM_ADMIN_TOKEN unset)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_d71f093408f04636bc91f85df44c811d | https://github.com/star-ga/mind-mem/issues/508 | 来源类型 github_issue 暴露的待验证使用条件。
## 14. 安全/权限坑 · 来源证据：[HIGH] T-006: Bound vault_scan / vault_sync filesystem walks (arbitrary host markdown exfil)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[HIGH] T-006: Bound vault_scan / vault_sync filesystem walks (arbitrary host markdown exfil)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_7bf148881d754982a8b6bbb0959436d0 | https://github.com/star-ga/mind-mem/issues/509 | 来源类型 github_issue 暴露的待验证使用条件。
## 15. 安全/权限坑 · 来源证据：[MEDIUM] N-02: REST rollback_proposal silently drops 'reason' field
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MEDIUM] N-02: REST rollback_proposal silently drops 'reason' field
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_afb67087422e43678c941140da7019de | https://github.com/star-ga/mind-mem/issues/510 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 16. 安全/权限坑 · 来源证据：[MEDIUM] N-03: Rate limiter collapses all stdio clients into 'default' bucket
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MEDIUM] N-03: Rate limiter collapses all stdio clients into 'default' bucket
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_0917cf4b43b34ffe8d43e599d353665c | https://github.com/star-ga/mind-mem/issues/513 | 来源类型 github_issue 暴露的待验证使用条件。
## 17. 安全/权限坑 · 来源证据：[MEDIUM] N-04: staged_change rollback dispatcher silently drops 'reason'
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MEDIUM] N-04: staged_change rollback dispatcher silently drops 'reason'
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ad9e7a85457041afbc88c886568b2657 | https://github.com/star-ga/mind-mem/issues/511 | 来源类型 github_issue 暴露的待验证使用条件。
## 18. 安全/权限坑 · 来源证据：[MEDIUM] T-003: propose_update input bounds bypass (rationale/tags written verbatim to SIGNALS.md)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MEDIUM] T-003: propose_update input bounds bypass (rationale/tags written verbatim to SIGNALS.md)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_32106da2cae04c0185f7a6331cd1ef8a | https://github.com/star-ga/mind-mem/issues/512 | 来源类型 github_issue 暴露的待验证使用条件。
## 19. 安全/权限坑 · 来源证据：`_handle_fed_resolve` accepts caller-supplied merged_payload without validating it against the conflict (http_transport…
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：`_handle_fed_resolve` accepts caller-supplied merged_payload without validating it against the conflict (http_transport.py:687-694)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_7bba956cb937439b85b35fb2c150b7e2 | https://github.com/star-ga/mind-mem/issues/528 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 20. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1160652179 | https://github.com/star-ga/mind-mem | issue_or_pr_quality=unknown
## 21. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1160652179 | https://github.com/star-ga/mind-mem | release_recency=unknown