# https://github.com/DanceNitra/inspeximus Project Manual
Generated at: 2026-07-25 16:57:50 UTC
## Table of Contents
- [Introduction, Design Philosophy & Competitive Position](#page-1)
- [Core API & The Four Memory Operations](#page-2)
- [Governance, Verifiable Erasure & EU AI Act Compliance](#page-3)
- [Integrations, MCP Server, CLI & Framework Adapters](#page-4)
## Introduction, Design Philosophy & Competitive Position
### Related Pages
Related topics: [Core API & The Four Memory Operations](#page-2), [Governance, Verifiable Erasure & EU AI Act Compliance](#page-3)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/DanceNitra/inspeximus/blob/main/README.md)
- [inspeximus/__init__.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/__init__.py)
- [inspeximus/core.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/core.py)
- [claims_audit.py](https://github.com/DanceNitra/inspeximus/blob/main/claims_audit.py)
- [governance_audit.py](https://github.com/DanceNitra/inspeximus/blob/main/governance_audit.py)
- [docs/AI_ACT.md](https://github.com/DanceNitra/inspeximus/blob/main/docs/AI_ACT.md)
- [docs/SECURITY.md](https://github.com/DanceNitra/inspeximus/blob/main/docs/SECURITY.md)
# Introduction, Design Philosophy & Competitive Position
## Purpose and Scope
Inspeximus is an audit and inspection framework for *verifiable, governable AI agent memory*. It targets a recurring and uncomfortable problem: AI memory systems silently drift, retain data past a delete call, and produce no receipt a regulator, customer, or operator can independently re-check. The project packages reusable primitives — `claims_audit.py` for factual and grounding claims, `governance_audit.py` for policy and compliance decisions, and the `mnemo` package for memory-level guarantees — under one namespace so any agent runtime can attach evidence-producing inspectors without re-implementing them. Source: [README.md:1-40]().
The repository draws a deliberate line between *what an agent did* (behavioral logging) and *what an agent remembers* (epistemic state). Inspeximus focuses on the second: tamper-evident writes, append-only history, erasure auditable against soft-delete residue, and signed receipts a third party can verify offline. The README frames the work as engineering over well-known primitives, with prior art credited inline rather than reinvented. Source: [README.md:42-78]().
The public surface lives in `inspeximus/__init__.py`, which re-exports the stable audit entry points behind a frozen `__all__` list. Internal helpers remain private under `inspeximus/core.py`, so consumers cannot accidentally couple against unreleased types. Source: [inspeximus/__init__.py:1-30]().
## Design Philosophy
Four principles recur across the codebase, the release notes, and the security policy.
**Verifiable by construction.** Every state transition that matters — a write, a forget, a correction — produces a hash-chained receipt. `inspeximus.core` exposes the chaining primitives so any caller can independently re-derive a receipt's link root without trusting the producer. Source: [inspeximus/core.py:1-60]().
**Opt-in hardening, not aggressive defaults.** Following the policy established in the `mnemo` 1.1.0 hardening pass and visible across the audit modules, Inspeximus keeps a conservative default and gates stricter checks behind explicit flags (e.g., `warn_unpinned=True`, `contained=` arguments on irreversible spends). The release notes state explicitly: "Both additions OPT-IN; default = 1.0.0 behaviour." Source: [README.md:80-110]().
**Cloud-free testability.** The full test suite runs without external services. The README highlights a 16-test, cloud-free suite that has already caught a real export gap during the 1.0.0 release cycle, plus GitHub Actions CI on Python 3.9, 3.11, and 3.12. Source: [README.md:55-75]().
**Compliance-shaped artifacts.** Receipts are designed to be the document a Data Protection Officer hands a regulator under GDPR Article 17 erasure or the EU AI Act record-keeping obligations. `docs/AI_ACT.md` maps each pillar to a specific article-level requirement, and `claims_audit.py` exposes a `compliance_receipt(...)` helper that packages the underlying audit into a signed, shareable bundle. Source: [docs/AI_ACT.md:1-50](), Source: [claims_audit.py:1-45]().
## Architecture at a Glance
The runtime is layered so that each layer only depends on the one below it.
```mermaid
flowchart TD
A[Agent Runtime] --> B[inspeximus package]
B --> C[claims_audit.py]
B --> D[governance_audit.py]
B --> E[mnemo memory + MCP server]
C --> F[Receipts: hash-chained, Ed25519]
D --> F
E --> F
F --> G[Regulator / DPO / Operator]
```
`governance_audit.py` consumes the same receipt format produced by `claims_audit.py`, so a policy decision and a factual claim share a single evidence substrate. `inspeximus/core.py` holds the schema and chaining logic shared by both auditors and by `mnemo`'s `ErasureAuditor`. The hardening notes in `docs/SECURITY.md` reinforce that even the security posture is treated as another auditable surface rather than an implicit invariant. Source: [governance_audit.py:1-55](), Source: [inspeximus/core.py:30-90](), Source: [docs/SECURITY.md:1-40]().
## Competitive Position
Inspeximus is not a vector database, not an LLM gateway, and not an observability platform. Its competitive position is narrower and deeper: it is the *evidence layer* for any of those.
- Compared to behavioral logging tools, Inspeximus operates on the agent's *memory writes*, not its prompts and completions. A log line cannot prove that a deleted value no longer physically exists; an Inspeximus audit can. This is the gap surfaced by the 1.4.0 soft-delete residual probes — the difference between an API returning 200 and the data actually being gone. Source: [README.md:112-150]().
- Compared to vector stores with native audit features, Inspeximus is store-agnostic. `forget_subject(...)` and the `ErasureAuditor`'s `compliance_receipt(...)` work across heterogeneous backends, producing one cross-store proof-of-erasure the regulator reads once. Source: [governance_audit.py:40-80]().
- Compared to in-house ERASE-style pipelines, Inspeximus ships the prior-art-credited primitives — Certificate Transparency-style external anchoring (RFC 6962), tamper-evident hash chains, Ed25519 signatures — already wired and tested, with a stable public API frozen in `mnemo.__all__`. Source: [inspeximus/__init__.py:15-35](), Source: [README.md:60-100]().
The release notes position 1.5.0 explicitly as "the governance / temporal pillar of verifiable memory," framing Inspeximus as a complement to recall and retrieval rather than a replacement for them. Source: [README.md:130-175]().
---
## Core API & The Four Memory Operations
### Related Pages
Related topics: [Introduction, Design Philosophy & Competitive Position](#page-1), [Governance, Verifiable Erasure & EU AI Act Compliance](#page-3), [Integrations, MCP Server, CLI & Framework Adapters](#page-4)
Related Source Files
The following source files were used to generate this page:
- [mnemo/__init__.py](https://github.com/DanceNitra/inspeximus/blob/main/mnemo/__init__.py)
- [mnemo/mnemo.py](https://github.com/DanceNitra/inspeximus/blob/main/mnemo/mnemo.py)
- [mnemo/deletion_manifest.py](https://github.com/DanceNitra/inspeximus/blob/main/mnemo/deletion_manifest.py)
- [mnemo/erasure_auditor.py](https://github.com/DanceNitra/inspeximus/blob/main/mnemo/erasure_auditor.py)
- [mnemo/code_guard.py](https://github.com/DanceNitra/inspeximus/blob/main/mnemo/code_guard.py)
- [mnemo/audit_bundle.py](https://github.com/DanceNitra/inspeximus/blob/main/mnemo/audit_bundle.py)
- [mnemo/witness_pool.py](https://github.com/DanceNitra/inspeximus/blob/main/mnemo/witness_pool.py)
- [examples/01_basics.py](https://github.com/DanceNitra/inspeximus/blob/main/examples/01_basics.py)
# Core API & The Four Memory Operations
The mnemo package inside inspeximus exposes a small, frozen public surface (`mnemo.__all__`) that treats agent memory the way a database treats a transaction log: every write is local, every read is explainable, every correction is auditable, and every deletion is a legal artifact. The Core API collapses that contract into four user-facing memory operations — `remember`, `recall`, `revert`, and `forget` — supported by governance helpers (`verify_writes`, `anchor`, `verify_consistency`, `spend_irreversible`) and an `ErasureAuditor` for proof-of-erasure receipts. Source: [mnemo/__init__.py]() (the `__all__` freeze was reaffirmed in the 1.0.0 release notes).
## Purpose and Scope
The Core API is the canonical entry point for any integrator. Everything in `mnemo.__all__` is the public, semver-locked contract; everything below it is the implementation surface that may change between minor versions. The four operations are deliberately orthogonal:
- `remember` is the only **write** primitive.
- `recall` is the only **read** primitive.
- `revert` is the only **in-place correction** primitive.
- `forget_subject` (delegated to the `deletion_manifest` + `erasure_auditor` submodules) is the only **erasure** primitive.
Anything an integrator wants to do — chat memory, RAG context, agent scratchpads, compliance logs — is expressed as a composition of these four. Source: [mnemo/__init__.py:__all__](); Source: [examples/01_basics.py:1-40]() (the canonical walkthrough in `01_basics.py` is organized around the same four verbs).
## The Four Operations
### 1. `remember(text, ...)` — write
`remember` appends a value to the local store and stamps it with metadata that `verify_writes` later consumes. From v1.1.0 onward, `Mnemo(max_text=N)` truncates oversize input and records `meta.truncated_from` so callers can detect silent availability loss rather than seeing an opaque exception. Source: [mnemo/mnemo.py:remember()](); Source: [examples/01_basics.py:remember-demo]().
Every write returns a tamper-evident receipt. Receipts are hash-chained and may be signed with Ed25519 when a `pubkey=` is supplied; `verify_writes(warn_unpinned=True)` surfaces the self-referential-pubkey footgun so integrators do not pin a key with no out-of-band provenance. Source: [mnemo/mnemo.py:verify_writes()](); Source: [mnemo/code_guard.py]()`s `warn_unpinned` branch.
### 2. `recall(query, ...)` — read
`recall` is value-ranked, lexically and semantically fused in "auto" mode, and applies per-type decay and consolidation. The signature stays deliberately small so the same call works whether the backend is the zero-dependency local store or an external MCP server exposing the same verbs over stdio. Source: [mnemo/mnemo.py:recall()](); Source: [mnemo/__init__.py:__all__]().
### 3. `revert(...)` — correct
`revert` is the correction channel that the 1.5.0 release notes describe alongside `retract_lineage` and `echo_guard`. Unlike a delete, a revert leaves an auditable trail showing the *previous* value, the corrective value, and the receipt that links them — so a downstream verifier can prove that the correction itself was authorised. Source: [mnemo/mnemo.py:revert()](); Source: [mnemo/deletion_manifest.py]() (the same lineage primitives underpin deletion).
This is also where `is_universal_executor(tool, signature)` and `spend_irreversible(tool=, contained=)` apply (v1.2.0). An uncontained universal executor (verb-polymorphic `shell`/`eval`/SQL/HTTP tools) is *denied outright* — reversibility is undecidable from the signature alone, so the call is refused before it can bypass `revert`. Source: [mnemo/code_guard.py:is_universal_executor()](); Source: [mnemo/code_guard.py:spend_irreversible()]().
### 4. `forget_subject(...)` — erase
Erasure is not a flag; it is a workflow. `forget_subject(basis=, authorized_by=, authorization=)` writes an erasure tombstone bound to a legal/operational basis, and `ErasureAuditor.compliance_receipt(subject, values, sign=, pubkey=, request_id=, basis=)` packages the audit as a signed **proof-of-erasure** receipt — the artifact a DPO hands a regulator under GDPR Art. 17 or the EU AI Act record-keeping rules. Source: [mnemo/deletion_manifest.py:forget_subject()](); Source: [mnemo/erasure_auditor.py:compliance_receipt()]().
Because "the API returned 200" and "it's gone" are two different things, v1.4.0 introduced **soft-delete residual probes** in the `ErasureAuditor`. These probes assert that a soft-deleted value no longer physically survives — i.e., that any subsequent compaction/vacuum/GC did its job. Source: [mnemo/erasure_auditor.py:residual_probes]().
## Governance Layer Around the Four
The four operations are the verbs; the governance layer is what makes the verbs composable under audit:
| Helper | Role | Source |
|---|---|---|
| `verify_writes` | Detect receipt tampering; surface unpinned-key risk. | [mnemo/mnemo.py:verify_writes()]() |
| `anchor` / `verify_consistency` | RFC 6962-style external anchor; catches history rewrite/rollback that `verify_writes` cannot (v0.7.22). | [mnemo/audit_bundle.py:anchor()](); [mnemo/audit_bundle.py:verify_consistency()]() |
| `is_universal_executor` | Detect verb-polymorphic tools whose reversibility is not decidable. | [mnemo/code_guard.py:is_universal_executor()]() |
| `spend_irreversible` | Apply the influence gate; deny uncontained universal executors. | [mnemo/code_guard.py:spend_irreversible()]() |
| `ErasureAuditor.compliance_receipt` | Package proof-of-erasure for regulators. | [mnemo/erasure_auditor.py:compliance_receipt()]() |
```mermaid
flowchart LR
R[remember] -->|hash-chained receipts| ST[(Local Store)]
Q[recall] <--> ST
V[revert] -->|lineage preserved| ST
F[forget_subject] -->|tombstone| M[deletion_manifest]
M --> EA[ErasureAuditor]
EA --> CR[signed proof-of-erasure receipt]
ST -. verify_writes .-> R
ST -. anchor / verify_consistency .-> EXT[(External Witness)]
CR -. spend_irreversible gate .-> CG[code_guard]
```
## Stability Contract and Known Friction
Since v1.0.0 the Core API is frozen in `mnemo.__all__`; governance/erasure tools live in submodules (`deletion_manifest`, `erasure_auditor`) and may evolve under their own semver. The 1.5.0 "provable forget" milestone is the latest governance pillar and does **not** change the four-operation contract. Source: [mnemo/__init__.py:__all__]().
One piece of community-flagged friction: the README's local-only integrity benchmark (`mnemo/probes/integrity_bench_revert.py --systems mnemo`) was reported in issue #1 to still require a missing `server/.env` and an OpenAI judge on fresh clones. The Core API itself is unaffected, but anyone running the benchmark as a "no-cloud" demo today should expect to provision the judge until that path is closed. Source: community issue #1, [mnemo/probes/integrity_bench_revert.py]().
---
## Governance, Verifiable Erasure & EU AI Act Compliance
### Related Pages
Related topics: [Introduction, Design Philosophy & Competitive Position](#page-1), [Core API & The Four Memory Operations](#page-2), [Integrations, MCP Server, CLI & Framework Adapters](#page-4)
Related Source Files
The following source files were used to generate this page:
- [inspeximus/erasure_auditor.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/erasure_auditor.py)
- [inspeximus/deletion_manifest.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/deletion_manifest.py)
- [inspeximus/audit_bundle.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/audit_bundle.py)
- [inspeximus/witness_pool.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/witness_pool.py)
- [inspeximus/witness_server.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/witness_server.py)
- [inspeximus/compliance.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/compliance.py)
# Governance, Verifiable Erasure & EU AI Act Compliance
The `mnemo` governance pillar provides a third-party-auditable channel for proving that a subject (user, session, line of reasoning) has been removed from every store that ever held it. It targets two regimes that have historically been treated as the same thing but are not: **"the delete endpoint returned 200"** and **"the data is physically and reconstructively gone, including in residual indexes, caches, derivative vectors, and backups"**. `mnemo` engineers the second one explicitly, with signed receipts, cross-store probes, and an optional external witness pool. Source: [inspeximus/erasure_auditor.py:1-80]().
## 1. The Erasure Auditor and Residual Probes
The core primitive is `ErasureAuditor`, which fans out subject-aware deletion probes across every backend the application declares (Redis, Postgres, vector stores, blob storage, file caches). Each probe is one of three classes: `*_native_delete` (calls the store's own `DEL`/`DELETE`), `*_keyword_index_delete` (verifies the subject's tokens are absent from full-text / inverted indexes), and `*_vector_residual_probe` (retrieves the top-k nearest neighbours and confirms the residual score for the subject has crossed a configured `residual_floor`). Source: [inspeximus/erasure_auditor.py:42-138]().
The `vector_residual_probe` is the load-bearing addition from the 1.4.0 line and exists because vector stores commonly mark a record deleted in a metadata column without compacting the underlying HNSW / IVF segments. A naive `verify()` against the metadata passes while the vector survives a `k=10` query for hours or days. The probe enforces that the post-deletion nearest-neighbour residual between the deleted embedding and any result is below `residual_floor` (default `1e-3`), which empirically catches "phantom recall" — a class of bug that surfaced in an r/RAG thread cited in the 1.4.0 release notes. Source: [inspeximus/erasure_auditor.py:118-176]().
## 2. Deletion Manifest and the Erasure Channel
Every effective erasure is anchored to a `DeletionManifest` that records `subject`, `authorized_by`, `authorization` (the legal/policy basis string — e.g., `"GDPR Art. 17"`, `"EU AI Act Art. 12 retention"`, `"user_request"`), and a hash-chained list of store-level reports. `forget_subject()` is the public entry: it is order-dependent and idempotent. Source: [inspeximus/deletion_manifest.py:30-91]().
```python
m = forget_subject(
"user_88421",
basis="GDPR Art. 17 erasure request, ticket #EU-2024-3318",
authorized_by="dpo@example.com",
authorization={"signed_by": "dpo_pubkey_ed25519:..."},
)
```
The manifest is itself append-only and content-addressed: `(subject, ts, prev_manifest_hash) -> manifest_hash`, which lets a downstream regulator replay the deletion history without trusting mnemo's runtime. A `manifest_id` here is what later gets quoted inside a `compliance_receipt`. Source: [inspeximus/deletion_manifest.py:94-147]().
The audit chain is collected into an `AuditBundle` so that an inspector (DPO, EU notified body, internal counsel) can hand a single tarball/JSON to legal. The bundle carries the manifests, the per-probe raw observations, the witness attestations (Section 3), and a JCS-canonicalised top-level `MERKLE_ROOT` over everything else. Because the bundle is content-addressed, a "snapshot of the deletion evidence" can be anchored externally (RFC 6962-style) to detect a later backfill or history rewrite. Source: [inspeximus/audit_bundle.py:1-72]().
## 3. Witness Pool and Witness Server
The trust model says: mnemo's receipts should be self-verifying **without** requiring trust in the mnemo process itself. To make that operational, the auditor splits the proof into two halves — **store-level** (probes that only the application can run, because they need row-level access) and **attestation-level** (signed countersignatures from independent witnesses). Source: [inspeximus/witness_pool.py:18-66]().
`WitnessServer` is the optional sidecar: a small HTTP service that returns a timestamped, Ed25519-signed attestation of the form `ATTEST(audit_bundle_hash, witness_seq, ts)` over a bundle it has been shown. `WitnessPool` aggregates N (configurable quorum, default `k=3` of `n=5`) such servers and treats a bundle as externally attested once it carries a quorum of distinct witness public keys on a strictly monotonic counter. A quorum attack on the witnesses requires compromising more than `k` independent keys in the same `ts_window`, which the auditor reports as a `quorum_at_risk` rather than a clean attestation. Source: [inspeximus/witness_server.py:28-104]().
```mermaid
flowchart LR
App[Application] -- forget_subject() --> Mf[DeletionManifest]
Mf -- probe fan-out --> EA[ErasureAuditor]
EA -- per-store residual --> St1[(Vector store)]
EA --> St2[(KV store)]
EA --> St3[(Blob store)]
Mf -- hash --> AB[AuditBundle]
AB -- present --> WS1[Witness 1]
AB --> WS2[Witness 2]
AB --> WS3[Witness 3]
WS1 --> WP[WitnessPool
quorum k-of-n]
WS2 --> WP
WS3 --> WP
WP -- compliance_receipt --> CR[compliance_receipt
signed JCS]
```
## 4. compliance_receipt and EU AI Act Alignment
The user-facing export is `ErasureAuditor.compliance_receipt(subject, values, sign=, pubkey=, request_id=, basis=)`. It packages the auditor run into a single signable JCS document — which stores were checked, which probes succeeded, the residual floor configuration, the manifest chain root, and the quorum of witness attestations — and signs it with an Ed25519 key whose public counterpart is embedded in the receipt itself. This is the artifact a DPO hands to a regulator under GDPR Art. 17 or to a notified body under EU AI Act record-keeping obligations (Art. 12 retention, Art. 14 human oversight, Annex IV technical documentation). Source: [inspeximus/compliance.py:40-118]().
The `basis=` argument is intentionally a free-text legal/policy citation so that the receipt remains jurisdiction-agnostic. The receipt also embeds a `merkle_root` over the included `values` snapshot — useful when the receipt is later presented as proof of a specific training-data exclusion (lineage-of-erasure) rather than just a runtime deletion. Source: [inspeximus/compliance.py:121-167]().
## 5. Operational Notes and Known Gaps
- **Soft-delete residual probes are zero-network by default**; the auditor synthesises them in-process so the mnemo-only benchmark in `probes/integrity_bench_revert.py --systems mnemo` runs locally. However, the README example as cited in issue #1 assumes a `server/.env` that does not exist on a fresh clone, and the harness still expects an OpenAI judge when more than one system is added — so the "fully local" claim holds only for the `mnemo`-single-system mode. Source: community issue #1.
- **Witness servers are opt-in**; with the pool disabled, receipts are still self-verifying but cannot defend against a hostile mnemo runtime rewriting the manifest chain after the fact.
- **Universal-executor gate** (`is_universal_executor`, in 1.2.0) complements the erasure channel by denying `spend_irreversible(contained=False)` for verb-polymorphic tools, ensuring an agent cannot bypass the audit by emitting its own deletions. Source: [inspeximus/compliance.py:18-39]().
Collectively these primitives turn "we deleted it" from an assertion into a hand-offable, third-party-verifiable artifact.
---
## Integrations, MCP Server, CLI & Framework Adapters
### Related Pages
Related topics: [Core API & The Four Memory Operations](#page-2), [Governance, Verifiable Erasure & EU AI Act Compliance](#page-3)
Related Source Files
The following source files were used to generate this page:
- [inspeximus/mcp_server.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/mcp_server.py)
- [inspeximus/cli.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/cli.py)
- [inspeximus/integrations/langgraph.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/integrations/langgraph.py)
- [inspeximus/integrations/langchain.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/integrations/langchain.py)
- [inspeximus/integrations/crewai.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/integrations/crewai.py)
- [inspeximus/integrations/llamaindex.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/integrations/llamaindex.py)
# Integrations, MCP Server, CLI & Framework Adapters
The repository exposes the `mnemo` agent-memory core through three surface areas: an MCP server (stdio), a CLI, and per-framework adapters. Together these let external agents (LangGraph, LangChain, CrewAI, LlamaIndex, raw MCP clients) speak to the same memory and governance primitives — `remember`, `recall`, `revert`, `forget_subject`, `anchor`, `verify_consistency`, `ErasureAuditor.compliance_receipt`, and friends — without depending on the cloud-hosted probe runner.
## MCP Server
The stdio-based MCP server is the canonical integration point introduced in the **mnemo 0.7.20** release. It exposes 12 tools over JSON-RPC and is zero-dependency, so a host only needs to launch the process.
- Transport: stdio (line-delimited JSON), per `inspeximus/mcp_server.py`.
- Tool surface (12): memory I/O (`remember`, `recall`, `consolidate`), correction/erasure (`revert`, `retract_lineage`, `echo_guard`, `forget_subject`), governance/audit (`anchor`, `verify_consistency`, `verify_writes`), and spend/reversibility gates (`spend_irreversible`, `is_universal_executor`).
- The server is framework-agnostic; framework adapters are thin wrappers around the same tool names so that behavior is identical across surfaces.
Source: [inspeximus/mcp_server.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/mcp_server.py)
Source: Release `mnemo 0.7.20 — Zero-dependency agent memory + MCP server (12 tools over stdio)` ([releases/tag/v0.7.20](https://github.com/DanceNitra/inspeximus/releases/tag/v0.7.20))
> Note from issue #1: the README's example `python mnemo/probes/integrity_bench_revert.py --systems mnemo` is documented as local-only but on a fresh clone the script fails before argument handling because `probes/integrity_bench_revert.py` requires a `server/.env` file and still invokes an OpenAI judge. This is a probes / harness issue, not an MCP-server issue, but it matters here because the MCP server is the *intended* local surface; the README should point users at the MCP tools instead of the probes script on a clean checkout.
Source: [issues/1](https://github.com/DanceNitra/inspeximus/issues/1) — "Integrity benchmark local-only command requires missing server/.env and still needs OpenAI judge"
## CLI
`inspeximus/cli.py` is the operator-facing entry point. It mirrors the MCP tool surface one-to-one so that shell users, CI scripts, and MCP hosts all reach the same code paths.
- Subcommands correspond to MCP tool names (`mnemo remember`, `mnemo recall`, `mnemo revert`, `mnemo forget-subject`, `mnemo anchor`, `mnemo verify-writes`, etc.).
- Governance flags (e.g., `--warn-unpinned` on `verify-writes`, `--basis` / `--authorized-by` on `forget-subject`, `--contained` on `spend-irreversible`) are the same keyword arguments exposed to MCP callers, so behavior is consistent.
- Output is plain text by default and JSON with `--json`, which is what the probes scripts consume when they bypass the LLM judge.
Source: [inspeximus/cli.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/cli.py)
Source: [releases/tag/v1.1.0](https://github.com/DanceNitra/inspeximus/releases/tag/v1.1.0) — `Mnemo(max_text=N)`, `verify_writes(warn_unpinned=True)`
Source: [releases/tag/v1.2.0](https://github.com/DanceNitra/inspeximus/releases/tag/v1.2.0) — `is_universal_executor`, `spend_irreversible(tool=, contained=)`
## Framework Adapters
Each adapter in `inspeximus/integrations/` is a thin shim that maps a framework-native concept (a LangChain `Memory` class, a CrewAI tool, a LlamaIndex `BaseMemory`, a LangGraph node) onto the underlying `Mnemo` instance and its MCP-shaped tool calls. They exist so that adopting mnemo does not require rewriting an existing agent.
- **LangChain** — `inspeximus/integrations/langchain.py` exposes a memory backend that returns LangChain-shaped `Memory` outputs from `Mnemo.recall`, with `Mnemo.remember` wired into the chain's save step.
- **LangGraph** — `inspeximus/integrations/langgraph.py` provides graph nodes (`remember_node`, `recall_node`, `revert_node`) so a LangGraph state machine can call mnemo tools as first-class graph steps, including the `spend_irreversible` gate inside tool-execution nodes.
- **CrewAI** — `inspeximus/integrations/crewai.py` registers the mnemo tools as CrewAI `Tool` objects, so a crew member can `forget_subject` or `revert` directly.
- **LlamaIndex** — `inspeximus/integrations/llamaindex.py` implements `BaseMemory` so that any LlamaIndex chat engine backed by mnemo inherits recall ranking, per-type decay, and the tamper-evident receipt chain.
All four adapters delegate — not reimplement — governance: erasure audit, anchoring, and reversibility classification still run inside `Mnemo` / `ErasureAuditor`. The adapters only translate I/O.
Source: [inspeximus/integrations/langgraph.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/integrations/langgraph.py)
Source: [inspeximus/integrations/langchain.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/integrations/langchain.py)
Source: [inspeximus/integrations/crewai.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/integrations/crewai.py)
Source: [inspeximus/integrations/llamaindex.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/integrations/llamaindex.py)
## Surface-to-Core Mapping
| Surface | Entry point | Talks to | Notes |
|---|---|---|---|
| MCP host | `mcp_server.py` (stdio, 12 tools) | `Mnemo`, `ErasureAuditor` | Zero-dep, canonical local surface |
| Operator shell | `cli.py` subcommands | `Mnemo`, `ErasureAuditor` | Mirrors MCP tool surface |
| LangGraph | `integrations/langgraph.py` nodes | `Mnemo` via node wrappers | `spend_irreversible` gate in tool-exec nodes |
| LangChain | `integrations/langchain.py` Memory | `Mnemo.recall` / `remember` | Drop-in `Memory` backend |
| CrewAI | `integrations/crewai.py` Tools | `Mnemo` tools as CrewAI `Tool`s | Direct `forget_subject` / `revert` from agents |
| LlamaIndex | `integrations/llamaindex.py` `BaseMemory` | `Mnemo.recall` | Inherits decay + receipts |
Source: [inspeximus/mcp_server.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/mcp_server.py); [inspeximus/cli.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/cli.py); [inspeximus/integrations/langgraph.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/integrations/langgraph.py); [inspeximus/integrations/langchain.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/integrations/langchain.py); [inspeximus/integrations/crewai.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/integrations/crewai.py); [inspeximus/integrations/llamaindex.py](https://github.com/DanceNitra/inspeximus/blob/main/inspeximus/integrations/llamaindex.py)
---
---
## Pitfall Log
Project: DanceNitra/inspeximus
Summary: Found 8 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.
## 1. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: capability.host_targets | https://github.com/DanceNitra/inspeximus
## 2. Capability evidence risk - Capability evidence risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/DanceNitra/inspeximus
## 3. Maintenance risk - Maintenance risk requires verification
- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: evidence.maintainer_signals | https://github.com/DanceNitra/inspeximus
## 4. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/DanceNitra/inspeximus
## 5. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/DanceNitra/inspeximus
## 6. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/DanceNitra/inspeximus/issues/1
## 7. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/DanceNitra/inspeximus
## 8. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/DanceNitra/inspeximus