Related Pages

Related topics: Federation, v4 Cognitive Kernel & Security Posture, Storage Backends, SQLite/Postgres Indexing & Recall Pipelines, MCP Server Surface, Client Integrations & Operational Tooling

Overview, Substrate & Governed-Write Architecture

1. System Purpose and Scope

Mind-mem is positioned in its MCP server instructions as *"persistent, auditable, contradiction-safe memory for coding agents"*, with the explicit contract that *"all proposals go through human review"* — Source: src/mind_mem/mcp/server.py:registration-block. The system exposes roughly 50 tools through the Model Context Protocol (stdio + opt-in HTTP) plus a small REST surface for governance operations. The latest release line is v4.0.18.

Three architectural pillars support that contract:

1. Substrate — where memory blocks physically live.
2. MCP tool surface — how AI agents read and propose.
3. Governed-write path — ACL whitelist, scope resolution, admin tokens, audit chain.

2. Substrate: Markdown, SQLite FTS, and Postgres

Mind-mem supports multiple storage backends chosen per workspace:

The switch is centralized in src/mind_mem/mcp/tools/memory_ops.py: _is_markdown_backend(ws) decides whether export_memory walks local .md files via parse_file() or fetches records through get_block_store(ws).get_all(active_only=False). index_stats() reads FTS metadata via sqlite_index.index_status(ws) and falls back to per-directory file counts when no FTS index exists.

The FTS index path is the substrate for recall, hybrid_search, pack_recall_budget, prefetch, and find_similar — all eight tools in src/mind_mem/mcp/tools/recall.py ultimately delegate to a shared _recall_impl choke point.

3. Governed-Write Architecture

The governed-write path is enforced in three layers.

3.1 ACL Whitelist

src/mind_mem/mcp/infra/acl.py maintains an _ALLOWED_TOOLS frozenset enumerating every tool that may be invoked through any MCP/HTTP endpoint. Tools registered on the FastMCP server but missing from this set are implicitly denied — Source: src/mind_mem/mcp/infra/acl.py:_ALLOWED_TOOLS-set. Recent additions include v3.11.0 lineage tools (validate_block, block_lineage, add_block_edge) and v3.11.1 backfill entries that had been silently failing acl_unknown_tool since v3.8.4.

check_tool_acl(tool_name, scope) returns None on allow or a JSON error envelope on deny. Admin tools additionally require scope ∈ {"admin", "full", "mind-mem:admin"} via _ADMIN_SCOPES.

3.2 Request-Scope Resolution

_get_request_scope() introspects bearer tokens / OIDC credentials and maps them to a scope string. Community issue #526 documents that this function fails open on introspection errors (src/mind_mem/mcp/infra/acl.py:139-142): any exception from the introspector is swallowed, the scope defaults to "user", and admin checks can be bypassed. The proposed fix is a "deny" sentinel that check_tool_acl rejects everywhere.

3.3 REST Auth Dependencies

src/mind_mem/api/rest.py wires FastAPI dependencies on each route:

• _require_auth for read endpoints (/v1/scan, /v1/contradictions)
• _require_admin for write endpoints (/v1/approve_apply, /v1/rollback_proposal)
• Depends(_rate_limit) is attached to every governance route

The HTTP transport additionally requires --allow-unauthenticated-localhost to start without auth (_enforce_http_auth_or_localhost in src/mind_mem/mcp/server.py); otherwise the server refuses to bind.

4. MCP Tool Surface and Registration Order

The FastMCP server (src/mind_mem/mcp/server.py) registers tools by domain. Registration order is significant: resources first, then tools, with the consolidated public.py dispatchers (recall, staged_change, memory_verify, graph, core, kernels, compiled_truth) registered last so the shadowed recall name routes through the mode-aware dispatcher — Source: src/mind_mem/mcp/server.py:_tools_public-register-block.

The compiled_truth_* family in src/mind_mem/mcp/tools/kernels.py is the substrate for the "contradiction-safe" claim: compiled_truth_add_evidence appends an EvidenceEntry, calls recompile_truth(), and persists via save_truth_page(); compiled_truth_contradictions invokes detect_contradictions(page) and returns pairwise conflict tuples.

flowchart LR
    A[MCP Client] -->|stdio| S[FastMCP server.py]
    A -->|HTTP + token| R[api/rest.py]
    R -->|Depends _require_admin| G[mcp/tools/governance]
    S --> C{acl.check_tool_acl}
    C -->|allowed| T[Domain tool modules]
    C -->|denied| E[acl_unknown_tool JSON error]
    T --> Sub[(Markdown / SQLite FTS / Postgres)]
    T --> Ac[audit_chain.py + Merkle tree]
    G --> SIGNALS[SIGNALS.md proposals]
    G --> Ac

5. Known Limitations (Community-Tracked)

• #526 — Critical (v4.0.7): ACL _get_request_scope fail-open on introspection exception (src/mind_mem/mcp/infra/acl.py:139-142).
• #530 — Medium (v4.0.8): build_index takes ~55s on a fresh 80KB workspace (src/mind_mem/sqlite_index.py:build_index).
• #525 / #524 — Medium: PG-backed mm recall returns [] and mm doctor --rebuild-cache reports errors=N because the local recall.db mirror is empty for PG workspaces.
• #515: test_rollback_removes_new_files fails on macOS/Windows runners, passes on Linux (tests/test_apply_engine.py:152).
• #513 — Medium: Rate limiter collapses all stdio clients into a single "default" bucket (mcp/infra/rate_limit.py:95-103).
• #512 — Medium: propose_update writes rationale/tags verbatim into SIGNALS.md with no length cap, bypassing the 500-char statement bound.
• #511 — Medium: staged_change(phase="rollback") silently drops the agent-supplied reason (mcp/tools/public.py:192).

See Also

• Architecture documentation: docs/architecture.md
• Specification: SPEC.md
• JS SDK reference: sdk/js/README.md
• Apply engine: src/mind_mem/apply_engine.py
• Audit chain: src/mind_mem/audit_chain.py
• Governance gate: src/mind_mem/governance_gate.py

Related Pages

Related topics: Overview, Substrate & Governed-Write Architecture, Storage Backends, SQLite/Postgres Indexing & Recall Pipelines, MCP Server Surface, Client Integrations & Operational Tooling

Federation, v4 Cognitive Kernel & Security Posture

mind-mem's v4 line (currently v4.0.18, released as of this writing) introduced two coupled subsystems: a Federation protocol that lets two or more mind-mem nodes reconcile their block graphs across an HTTP transport, and a Cognitive Kernel that owns the consolidation, feature-flagging, and circuit-breaking logic the federation layer relies on. The two are inseparable from a security standpoint: federation is opt-in (gated by --transport http), but once it is enabled the kernel's ACL, rate limit, and auth enforcement become the operator's last line of defence.

Federation Protocol & Transport

Federation is implemented as a request/response surface mounted on the MCP HTTP transport. Two endpoints matter:

• fed_resolve — accepts a caller-supplied merged_payload to settle a detected conflict (src/mind_mem/http_transport.py:687-694).
• The client side lives in src/mind_mem/v4/federation_client.py:240-251, which calls urllib.request.urlopen directly against an operator-supplied base_url.

The merge algorithm itself is THREE_WAY_MERGE in src/mind_mem/v4/federation.py:359-360, which is supposed to advance the per-block vector clock (vclock) so that detect_conflict stops re-reporting an already-resolved conflict on every pass.

flowchart LR
    A[Local node<br/>detect_conflict] --> B[fed_resolve<br/>http_transport.py:687]
    B --> C{Validate merged_payload<br/>vs conflict state}
    C -- valid --> D[THREE_WAY_MERGE<br/>federation.py:359]
    C -- invalid --> E[Reject]
    D --> F[Bump vclock]
    F --> G[Persist + emit receipt]
    H[FederationClient<br/>federation_client.py:240] --> B

Operators enable federation with --transport http. The default stdio path does not expose any federation endpoints. When HTTP is enabled, src/mind_mem/mcp/server.py refuses to start unless one of MIND_MEM_TOKEN, MIND_MEM_ADMIN_TOKEN, or OIDC_ISSUER+OIDC_AUDIENCE is configured, or the operator passes --allow-unauthenticated-localhost AND binds to 127.0.0.1/localhost/::1 (_LOOPBACK_HOSTS).

v4 Cognitive Kernel Architecture

The cognitive kernel is the home of v4's autonomous behaviour:

The kernel is what mm recall, mm scan, and the federation client all consult through _workspace() and _check_workspace() helpers. The kernel itself never owns network I/O — the FederationClient is a thin wrapper that goes directly to urllib, which is why hardening gaps on the client side translate directly into kernel-level exposure.

Security Posture (ACL, Auth, Hardening)

The defence-in-depth model has three layers:

1. HTTP auth gate. src/mind_mem/mcp/server.py hard-refuses to start the HTTP transport without a configured token/OIDC issuer, except on loopback with an explicit opt-in.
2. Tool ACL. src/mind_mem/mcp/infra/acl.py defines _PUBLIC_TOOLS (read-only surface) and _ADMIN_SCOPES = {"admin", "full", "mind-mem:admin"}. check_tool_acl(tool_name, scope) returns None for allowed calls and a JSON error envelope otherwise. Issue #526 added a fail-closed sentinel (scope == "deny") that fires when token introspection raises, so any introspection exception now rejects every tool — admin or user.
3. Rate limiting. src/mind_mem/mcp/infra/rate_limit.py:95-103 enforces a 120/min window. In stdio mode the bucket key collapses to the literal string "default", which means all 57 tools share one window — see issue #513 below.

The dispatcher in src/mind_mem/mcp/tools/public.py:192 folds propose / approve / rollback into one staged_change entry point; the rollback branch dispatches to governance.rollback_proposal.

Known Security Issues & Failure Modes

The v4.0.x line has accumulated a number of tracked defects that operators should know about before enabling federation:

• #526 — ACL fail-open (Critical). _get_request_scope previously swallowed introspection exceptions. Fixed in v4 by routing any exception to the "deny" scope; see acl.py:139-142. *Source: src/mind_mem/mcp/infra/acl.py:139-142.*
• #529 — FederationClient lacks hardening (High). No scheme allowlist, no redirect cap, no response-size cap, no TLS pinning. urllib.request.urlopen is invoked directly on the operator-supplied base_url at federation_client.py:240-251. Mitigation today is operator-side: pin the upstream, run behind a reverse proxy, or disable federation.
• #528 — Unvalidated merged_payload (Critical). _handle_fed_resolve accepts whatever merged payload the caller sends without cross-checking it against the conflict state in http_transport.py:687-694. Until this is patched, treat federation as an internal-only surface.
• #527 — THREE_WAY_MERGE vclock not bumped (Critical, functional). Resolved conflicts recur on every detect_conflict pass because federation.py:359-360 doesn't advance the vector clock. This is a correctness bug, not a security one, but it floods audit logs and can mask real conflicts.
• #512 — propose_update bounds bypass (Medium). governance.py caps statement at 500 chars but writes rationale and tags verbatim into SIGNALS.md. An adversarial caller can stuff arbitrarily large payloads into the signal log.
• #511 — staged_change(rollback) drops reason (Medium). The dispatcher silently drops the rationale/reason field at public.py:192. Agents get no audit trail for rollbacks.
• #513 — Rate-limit bucket collapse (Medium). All 57 stdio tools share one bucket keyed on "default". Two concurrent stdio clients exhaust each other's quota.

Together these defects show the federation surface is functional but unhardened: it should be enabled only on a trusted network with a reverse proxy in front, while the items above are worked through. The v3.2.0 ACL hardening (issue #526 fix) is the template for how subsequent issues are expected to land — fail-closed by default, with explicit sentinel values rather than implicit exception swallowing.

See Also

• ACL & Tool Surface: src/mind_mem/mcp/infra/acl.py
• MCP Server Boot: src/mind_mem/mcp/server.py
• Federation Conflict Handling: src/mind_mem/v4/federation.py
• Governance Staging & Rollback: src/mind_mem/mcp/tools/governance.py, src/mind_mem/mcp/tools/public.py
• Community: issues #526, #527, #528, #529, #511, #512, #513 in the mind-mem tracker.

Related Pages

Related topics: Overview, Substrate & Governed-Write Architecture, Federation, v4 Cognitive Kernel & Security Posture, MCP Server Surface, Client Integrations & Operational Tooling

Storage Backends, SQLite/Postgres Indexing & Recall Pipelines

Overview & Backend Taxonomy

Mind-mem persists memory as "blocks" and exposes retrieval through a small number of interchangeable storage backends. The block-of-record for a workspace is determined by the active backend declared in mind-mem.json, and every retrieval surface (MCP, REST, Go SDK) resolves blocks through the same backend switchboard. There are two fundamentally different shapes:

The MCP server registers the same tool set regardless of backend. Tools always look up the workspace via the resolver in mcp/infra/workspace.py and only then branch on backend type. Source: src/mind_mem/mcp/server.py:62-80 (tool module registration) and src/mind_mem/mcp/infra/workspace.py:30-58 (backend resolution contract).

Workspace Resolution & Block Store Layer

_check_workspace(ws) is the gate every tool runs through. It validates that the workspace root exists and that the configured backend's invariants hold. For the markdown family the invariant is a decisions/ directory on disk; for any other backend the invariant is that the configured block store answers to a probe (ping() or list_blocks()). Source: src/mind_mem/mcp/infra/workspace.py:30-58.

The split is explicit: a markdown or encrypted backend keeps blocks in local Markdown files, while a non-Markdown backend (e.g. postgres) keeps them in the store. The list of "markdown-family" backends is centralized in _MARKDOWN_BACKENDS, and the dispatch for store-based backends is handled by _check_store_backend. Source: src/mind_mem/mcp/infra/workspace.py:55-58.

Two helper selectors bridge tools to backends:

• _backend_name(ws) — returns the configured backend name.
• get_block_store(ws) — returns the active block-store object (MarkdownBlockStore, EncryptedBlockStore, PostgresBlockStore, etc.). Source: src/mind_mem/mcp/tools/memory_ops.py:30-46 (backend name helper and _is_markdown_backend).

Tool access to retrieval-sensitive surfaces is gated by check_tool_acl, which rejects scope == "deny" (the fail-closed sentinel produced when token introspection raises). Source: src/mind_mem/mcp/infra/acl.py:139-142.

SQLite FTS5 Indexing & Recall Pipeline

For markdown-family workspaces the canonical index is a SQLite FTS5 database named recall.db. The FTS path is derived by fts_db_path(ws) from sqlite_index._db_path, and it backs every ranked retrieval tool. Source: src/mind_mem/mcp/tools/memory_ops.py:54-70 (fts_db_path import and index_stats FTS probing).

The recall surface routes every query through _recall_impl, which selects the active backend (BM25, hybrid, or auto) and applies per-stage budgets. Eight tools share that choke point: recall, recall_with_axis, hybrid_search (deprecated alias), pack_recall_budget, prefetch, intent_classify, find_similar, and retrieval_diagnostics. Source: src/mind_mem/mcp/tools/recall.py:1-20(module docstring listing the shared recall engine).

memory_ops mirrors the FTS surface with lifecycle tools: index_stats reports total_blocks, last_build, stale_files, and db_size_bytes from sqlite_index.index_status(ws); reindex rebuilds the FTS index; export_memory walks every active block (Markdown or store-based) and emits a JSONL dump with a max_blocks cap. Source: src/mind_mem/mcp/tools/memory_ops.py:54-130(index_stats, export_memory, and backend-aware block enumeration).

flowchart TD
    A[Client recall request<br/>MCP / REST / Go SDK] --> B[_check_workspace<br/>mcp/infra/workspace.py]
    B --> C{Backend type?}
    C -->|markdown / encrypted| D[SQLite FTS5<br/>recall.db<br/>sqlite_index.py]
    C -->|postgres / other store| E[Block store FTS<br/>block_store_postgres.py]
    D --> F[_recall_impl<br/>recall.py — BM25 / hybrid]
    E --> F
    F --> G[Top-K result envelope<br/>_schema_version tagged]
    G --> H[Return via MCP tool / REST / Go]

The Go SDK mirrors the same axis with a SearchBackend enum (BackendAuto, BackendBM25, BackendHybrid) and BlockTier (WORKING / ARCHIVAL / COLD) on the Block type, so the same three-way choice is exposed to non-Python clients. Source: sdk/go/types.go:1-58 (Go type definitions).

Postgres-Backed Mode, Recall Coupling & Known Issues

When the workspace declares a non-Markdown backend, the block-of-record lives in the external store, and the local recall.db no longer holds the full corpus. Several open issues describe the resulting coupling problems:

• mm recall returns [] despite PG FTS hits (issue #525). A Postgres-backed workspace whose mind_mem.blocks table contains query matches can still return empty results from the recall tool, because the recall code path does not always fall back to the PG FTS view when the local cache is missing rows. Source: src/mind_mem/mcp/tools/recall.py:30-50(_recall_impl import surface) and src/mind_mem/mcp/tools/memory_ops.py:54-70(FTS-only probing in index_stats).
• mm doctor --rebuild-cache errors on PG workspaces (issue #524). rebuild-cache writes into the local recall.db and fails with sqlite_count_error: "no such table: blocks" because the local SQLite schema does not exist for PG-only blocks. Source: src/mind_mem/mcp/tools/memory_ops.py:54-90(FTS index probing in index_stats).
• build_index perf regression on fresh 80 KB workspace (issue #530). tests/test_sqlite_index.py::TestBuildIndex::test_incremental_detects_in_place_edit_past_64kb takes ~55 s on a fresh workspace. The component is sqlite_index.py:build_index. Source: src/mind_mem/mcp/tools/memory_ops.py:54-70(shared use of sqlite_index).

The REST API exposes the same retrieval surface as POST /v1/recall and protects it with a per-token rate limiter plus an admin-scope guard for mutating governance endpoints (/v1/approve_proposal, /v1/rollback_proposal). Source: src/mind_mem/api/rest.py:1-80(REST routing and dependency wiring).

See Also

• MCP tool decomposition plan referenced in src/mind_mem/mcp/tools/recall.py:1-20 and src/mind_mem/mcp/tools/memory_ops.py:1-30.
• Block lineage and quality tools: src/mind_mem/mcp/tools/lineage.py and src/mind_mem/mcp/tools/audit.py`.
• Web console client that consumes the bundle format from /v1/recall: web/README.md.

Related Pages

Related topics: Overview, Substrate & Governed-Write Architecture, Federation, v4 Cognitive Kernel & Security Posture, Storage Backends, SQLite/Postgres Indexing & Recall Pipelines

MCP Server Surface, Client Integrations & Operational Tooling

Overview and Purpose

The MCP (Model Context Protocol) server is mind-mem's primary integration surface for AI clients such as Claude Code, Codex CLI, Cursor, Windsurf, and any other FastMCP-compatible agent runtime. It exposes the workspace's block index, governance pipeline, audit chains, retrieval engine, and external tool bridges (arch-mind, vault, model audit) through a single, decomposable tool surface.

Historically, the entire MCP server lived in a single mcp_server.py monolith (4,604 LOC, 57 tools, 8 resources). The v3.2.0 §1.2 decomposition plan migrated that monolith into a per-domain package layout under src/mind_mem/mcp/ while preserving every public symbol via re-export shims. As stated in src/mind_mem/mcp/__init__.py, the old mcp_server surface stays unchanged so downstream callers never observe the migration.

The MCP layer is augmented by a REST surface (src/mind_mem/api/rest.py) that mounts the same governance, recall, and memory tools as HTTP endpoints behind the same ACL and rate-limit infrastructure.

Package Architecture

The decomposition splits MCP code into two subtrees: mind_mem.mcp.infra.* for cross-cutting helpers and mind_mem.mcp.tools.* for the per-domain @mcp.tool modules.

flowchart TD
    Client[FastMCP Client / REST Client] --> Server[mcp/server.py]
    Server --> Tools[mcp/tools/*.py]
    Server --> Resources[mcp/resources.py]
    Tools --> Helpers[mcp/tools/_helpers.py]
    Tools --> Infra[mcp/infra/*]
    Infra --> Workspace[workspace.py]
    Infra --> ACL[acl.py]
    Infra --> RateLimit[rate_limit.py]
    Tools --> Backend[mind_mem core:<br/>recall, governance_bench,<br/>sqlite_index, ontology, ...]
    REST[api/rest.py] --> Tools
    Client -.auth.-> ACL
    Client -.rl.-> RateLimit

Each domain submodule owns a register(mcp) function called by src/mind_mem/mcp/server.py to wire its tools onto the shared FastMCP instance. The dispatcher tools (recall, staged_change, memory_verify, graph, core, kernels, compiled_truth) are registered last via _tools_public.register(mcp) so the shadowed recall name routes through the mode-aware dispatcher. Source: src/mind_mem/mcp/server.py.

Tool Domains

Resources are co-located in src/mind_mem/mcp/resources.py: mind-mem://decisions, mind-mem://tasks, mind-mem://entities/{type}, mind-mem://signals, mind-mem://contradictions, mind-mem://health, mind-mem://recall/{query}, mind-mem://ledger.

Cross-Cutting Infrastructure

Workspace Resolution

Workspace selection uses a per-request ContextVar override before falling back to MIND_MEM_WORKSPACE or the current working directory. The override is set through use_workspace(...), allowing the REST layer to scope workspace selection to the request task without racing against other concurrent requests that mutate shared process state. Source: src/mind_mem/mcp/infra/workspace.py.

Shared Tool Helpers

mcp/tools/_helpers.py hosts private path resolvers (_signal_store_path, _kg_path, _core_dir) and lazy singletons (_ontology_registry which preloads the in-box software_engineering_ontology, _change_stream, _core_registry). It also re-exports get_logger, metrics, and traced so each tool module avoids cross-package edges and keeps the arch-mind modularity Q16.16 metric high.

Auth and Transport Hardening

The v3.7.0 H4 contract, enforced by _enforce_http_auth_or_localhost in src/mind_mem/mcp/server.py, refuses to expose the MCP HTTP transport without authentication. Either MIND_MEM_TOKEN, MIND_MEM_ADMIN_TOKEN, or OIDC_ISSUER+OIDC_AUDIENCE must be configured, OR the operator passes --allow-unauthenticated-localhost AND binds to a loopback interface (127.0.0.1, localhost, ::1).

The REST surface mounts the same governance endpoints behind the _require_auth / _require_admin dependencies and the shared _rate_limit dependency. Source: src/mind_mem/api/rest.py.

Operational Tooling and Known Issues

Recall Path Notes

recall is the most heavily used tool. The eight recall-domain tools share a single _recall_impl backend switchboard that selects between BM25 (SQLite FTS) and hybrid retrieval. hybrid_search remains as a deprecated alias that calls _recall_impl. retrieval_diagnostics exposes per-stage rejection histograms to aid tuning. Source: src/mind_mem/mcp/tools/recall.py.

The recall path has known sensitivity to the underlying index backend. Community issues #524 and #525 report that on Postgres-backed workspaces, mm doctor --rebuild-cache produces sqlite_count_error: "no such table: blocks" against the local recall.db, and mm recall <query> returns [] even when direct psql FTS finds matches. This indicates the recall tool path assumes a populated local SQLite cache and does not yet transparently fall back to the PG FTS.

Build-Index Performance

Issue #530 reports that build_index on a fresh 80 KB workspace takes ~55 seconds, traced to src/mind_mem/sqlite_index.py:build_index. The MCP reindex and index_stats tools are the user-visible entry points onto that path. On large workspaces, callers should expect the first reindex to dominate the request budget.

Governance Input Bounds

Issue #512 (T-003) records that propose_update caps statement at 500 characters but writes rationale and tags verbatim to SIGNALS.md. The MCP propose_update tool is the agent-facing entry onto that path; agents should sanitize those fields before submission. Source: src/mind_mem/mcp/tools/governance.py.

Staged-Change Rollback

Issue #511 (N-04) notes that staged_change(phase="rollback") silently drops the rationale field that the agent caller passed. Operators relying on the dispatcher should keep the rationale in the request envelope even though it is not currently surfaced in the response.

Vault Bridge Allowlist

vault_scan / vault_sync reject every request when MIND_MEM_VAULT_ALLOWLIST is empty (T-006 hardening against arbitrary host markdown exfiltration). The legacy open behaviour is reachable only via MIND_MEM_VAULT_ALLOW_ANY=true. Source: src/mind_mem/mcp/tools/agent.py.

Arch-mind Binary Resolution

The arch-mind bridge wraps an external binary located via the ARCH_MIND_BIN environment variable (falling back to PATH). mind-mem trusts the binary's canonical AST schema and Q16.16 determinism contract and does no metric arithmetic of its own. Set ARCH_MIND_BIN in the deployment env when arch-mind ships from a non-standard location. Source: src/mind_mem/mcp/tools/arch_mind.py.

See Also

• src/mind_mem/mcp/__init__.py — decomposition rationale and PR staging
• src/mind_mem/mcp/server.py — tool registration order and HTTP auth gate
• src/mind_mem/mcp/resources.py — read-only MCP resources
• src/mind_mem/api/rest.py — REST equivalents of governance + recall tools
• docs/v3.2.0-mcp-decomposition-plan.md — 16-PR migration plan referenced by every module docstring

Doramagic Pitfall Log

Found 20 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/star-ga/mind-mem/issues/524

2. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/star-ga/mind-mem/issues/525

3. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/star-ga/mind-mem/issues/530

4. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/star-ga/mind-mem

5. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/star-ga/mind-mem

6. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/star-ga/mind-mem/issues/515

7. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/star-ga/mind-mem

8. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/star-ga/mind-mem

9. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/star-ga/mind-mem

10. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/star-ga/mind-mem/issues/526

11. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/star-ga/mind-mem/issues/529

12. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/star-ga/mind-mem/issues/527

Community Discussion Evidence

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

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