{ "markdown": "

MemoryGuard

\n\n\n\n

\n Governed shared memory for coding agents.
\n Local-first MCP memory with automatic organization, scoped rules, evidence, and rollback.\n

\n\n

\n \"PyPI\n \"CI\n \"Python\n \"MIT\n 中文文档\n

\n\n> Let agents write without turning shared memory into an unreviewed pile.\n> MemoryGuard organizes each write, preserves the evidence behind changes, and\n> keeps governance decisions reversible.\n>\n> **No account. No remote server. No remote telemetry. Local-only usage telemetry\n> is optional and stores bounded, privacy-preserving aggregates locally.**\n\n

\n Quick start ·\n Upgrade ·\n Knowledge Library ·\n Architecture ·\n Supported hosts ·\n Privacy and safety\n

\n\n

\n \"Animated\n

\n\n

\n A synthetic governed projection: signals move through memory categories while raw conversation text remains outside the graph.\n

\n\n## What's New in v0.7.11\n\nv0.7.11 is a public documentation and discovery consistency release. Runtime\nbehavior summarized here originates in v0.7.9:\n\n- **Canonical memory and rule governance:** related rules, habits, and memories\n converge through one canonical read/write path while evidence, source links,\n graph branches, supersede history, conflict review, and settlement remain\n auditable and reversible.\n- **Readable multi-agent governance:** verified program identities, readable\n labels, safe family icons, shared-group scope, risk explanations, stale-conflict\n closure, seven governance pages, and a separate Token usage-and-savings entry\n keep daily governance understandable.\n- **Local usage and savings view:** the Token page shows local MCP conversion\n events and seven-/thirty-day estimated baseline-versus-delivered units.\n Provider token measurements are used only when reported (currently Codex and\n Grok); Claude, Cursor, and Trae remain explicitly unsupported. No conversation\n body, account, path, or instance identifier is stored.\n- **Codex lifecycle and runtime alignment:** terminal-thread evidence gates\n reclamation of Codex-owned leaked cohorts; ordinary turns remain resumable.\n Installed repair aligns MCP and lifecycle Hooks to the current interpreter\n while preserving Agent/shared-group identity and fail-closed boundaries.\n- **Evidence and discovery:** `scripts/benchmark_usage_telemetry.py` documents\n reproducible seven-/thirty-day local measurements with explicit coverage and\n no-sample semantics. Releases are published through GitHub OIDC to\n [GitHub Releases](https://github.com/irisxc4/memoryguard/releases),\n [PyPI](https://pypi.org/project/agent-memguard/), and the official MCP\n Registry. Verify current package and registry status through those live\n records. No Glama score or third-party directory listing is implied.\n\nSee the [v0.7.11 release note](docs/releases/v0.7.11.md) and\n[release history](CHANGELOG.md).\n\nEarlier release details are kept in the [Changelog](CHANGELOG.md) and\n[GitHub release records](https://github.com/irisxc4/memoryguard/releases).\n\n### Token evidence and demo\n\nRun the benchmark only against an authorized local workspace:\n\n```powershell\npython scripts/benchmark_usage_telemetry.py --workspace . --window-days 7 --sync\n```\n\nRead [the benchmark guide](docs/benchmarks/README.md) for measured,\nestimated, derived, and unsupported semantics. Use [the demo recording\nchecklist](docs/benchmarks/demo-script.md) for a sanitized walkthrough. The\nrepository's synthetic graph artwork is not a live product capture; it is not\nevidence of usage or savings.\n\n## Major V2 refactor in v0.6.0\n\nv0.6.0 was a production data-plane refactor, not a storage-only upgrade:\n\n- **Authoritative V2 domains:** Memory, Rules, Evidence, Content, Runtime, Projection, Assets, CodeGraph, Skills, and System state are separated into explicit SQLite domains with governed boundaries.\n- **Explicit cutover:** `V1_ACTIVE → V2_BUILDING → V2_READY → V2_ACTIVE` is fail-closed; V2 never silently falls back to legacy stores or dual-writes after READY/ACTIVE.\n- **Lossless migration:** frozen-source preparation uses coherent SQLite online backups, validates source/target evidence, rechecks live-source drift, and preserves V1 data plus migration backups for rollback.\n- **Native routing:** MCP, CLI, GUI, and Hook surfaces are classified explicitly; the release closed the 233-surface cutover with 138 implemented routes, 95 retired routes, and zero neutral/blocker routes.\n- **Governed intelligence:** Rule lifecycle and RuleMerge, extraction/enrichment, External MCP import, provider control-plane, conversation history, Knowledge Library, and GUI governance all use the V2 evidence and decision paths.\n- **Operational evidence:** Reference Audit, per-domain SQLite health, guarded maintenance, rollback evidence, and safe unbound diagnostics are part of readiness and operations.\n\n## Why MemoryGuard\n\nPersistent memory solves storage. It does not solve governance.\n\nWhen several coding agents write into the same context, records become\nduplicated, stale, contradictory, over-broad, or unsafe to reuse. MemoryGuard\nsits between coding agents and their shared memory to keep that context usable.\n\n| Without governance | With MemoryGuard |\n|---|---|\n| Notes accumulate without a canonical state | Writes are classified, deduplicated, superseded, or surfaced as conflicts |\n| A correction silently destroys the old value | Evidence and supersede chains preserve what changed and why |\n| Tokens and credentials can remain active | Sensitive-looking content is quarantined from active memory |\n| Every write needs manual approval | Agents write normally; people review exceptions and outcomes |\n| Raw chat logs leak into future context | Conversation history remains a separate, explicitly read evidence archive |\n\n## System architecture\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"themeVariables\":{\"background\":\"#071521\",\"fontFamily\":\"Arial, sans-serif\",\"fontSize\":\"14px\",\"primaryTextColor\":\"#EEF4F8\",\"lineColor\":\"#557287\",\"edgeLabelBackground\":\"#071521\",\"clusterBkg\":\"#0A1A29\",\"clusterBorder\":\"#27445A\"},\"flowchart\":{\"htmlLabels\":true,\"curve\":\"basis\",\"nodeSpacing\":32,\"rankSpacing\":48,\"padding\":14}}}%%\nflowchart TB\n Hosts[\"CODING-AGENT HOSTS
Claude Code · Codex · Cursor · TRAE    \"]:::host\n Gateway[\"LOCAL INTEGRATION
MCP stdio · redirect rules · lifecycle hooks    \"]:::gateway\n\n subgraph Core[\"GOVERNANCE CORE    \"]\n direction LR\n Identity[\"TRUST
identity · scope    \"]:::core\n MemoryAPI[\"MEMORY
governed I/O    \"]:::active\n Rules[\"RULES
scope · assignment    \"]:::rule\n HistoryAPI[\"HISTORY
search · timeline    \"]:::history\n Security[\"SAFETY
validate · quarantine    \"]:::danger\n\n Identity --> MemoryAPI\n Identity --> Rules\n Identity --> HistoryAPI\n MemoryAPI --> Security\n end\n\n subgraph Stores[\"LOCAL GOVERNED STORES    \"]\n direction LR\n SharedDB[(\"V2 DOMAIN STORES
Memory · Rules · Evidence · Content    \")]:::store\n HistoryDB[(\"HISTORY STORE
isolated conversations    \")]:::historyStore\n AuditDB[(\"RECOVERY STORE
versions · receipts · backups    \")]:::store\n end\n\n Bootstrap[\"BOUNDED CONTEXT BOOTSTRAP
mandatory rule pack · relevant recall    \"]:::bootstrap\n Control[\"HUMAN CONTROL
CLI · desktop governance console    \"]:::surface\n\n Hosts --> Gateway --> Identity\n MemoryAPI --> SharedDB\n Rules --> SharedDB\n HistoryAPI --> HistoryDB\n Security --> AuditDB\n SharedDB --> Bootstrap\n Control --> Identity\n\n classDef host fill:#12243A,stroke:#38D5C8,color:#EEF4F8,stroke-width:1.4px;\n classDef gateway fill:#0D3338,stroke:#38D5C8,color:#EEF4F8,stroke-width:2.4px;\n classDef core fill:#12243A,stroke:#557287,color:#EEF4F8,stroke-width:1.4px;\n classDef active fill:#0D383A,stroke:#38D5C8,color:#EEF4F8,stroke-width:2px;\n classDef rule fill:#3B2C18,stroke:#F3B562,color:#EEF4F8,stroke-width:1.8px;\n classDef history fill:#102F45,stroke:#73C7F5,color:#EEF4F8,stroke-width:1.8px;\n classDef danger fill:#3A2028,stroke:#EA6A6A,color:#EEF4F8,stroke-width:1.8px;\n classDef bootstrap fill:#EEF4F8,stroke:#38D5C8,color:#071521,stroke-width:2.4px;\n classDef store fill:#0B1624,stroke:#7F96A8,color:#EEF4F8,stroke-width:1.4px;\n classDef historyStore fill:#102436,stroke:#73C7F5,color:#EEF4F8,stroke-width:1.4px;\n classDef surface fill:#EEF4F8,stroke:#38D5C8,color:#071521,stroke-width:2px;\n\n style Core fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8\n style Stores fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8\n linkStyle default stroke:#557287,stroke-width:1.4px;\n```\n\n## Quick start\n\n### MCP Registry metadata\n\nThis package exposes a local stdio MCP server as `io.github.irisxc4/memoryguard`.\nRegistry metadata is kept in [`server.json`](server.json), and the marker above\nships with the PyPI package README. Releases are published through GitHub OIDC\nto PyPI and the official MCP Registry. Verify the current package version and\nthe Registry entry's active/latest state through their live public records.\n\n### 1. Install\n\n```bash\npython -m pip install agent-memguard\n```\n\nFor the desktop governance console:\n\n```bash\npython -m pip install \"agent-memguard[gui]\"\n```\n\n### 2. Authorize the current project\n\n```bash\nmemoryguard source add .\n```\n\n### 3. Connect or repair your coding agent\n\nGlobal provider configuration is rebuilt from the real binding in the canonical user data home. The command is idempotent and removes superseded MemoryGuard project-level overrides after a successful global takeover.\n\n```bash\n# Repair one provider\nmemoryguard provider repair claude\nmemoryguard provider repair codex\nmemoryguard provider repair cursor\nmemoryguard provider repair trae\n\n# Repair every detected provider\nmemoryguard provider repair all\n```\n\nRestart the host after installation, then verify the integration:\n\n```bash\nmemoryguard doctor\nmemoryguard mcp-status\nmemoryguard hooks status --provider all\n```\n\nLaunch the desktop console:\n\n```bash\nmemoryguard gui\n```\n\n`memoryguard-gui .` remains available for desktop shortcuts. A bare\n`memoryguard gui` always opens the canonical user-level control directory\n(default `%LOCALAPPDATA%\\MemoryGuard` on Windows), so running it from a project\nor from `C:\\Windows\\System32` cannot silently switch databases.\n`MEMORYGUARD_WORKSPACE` is an explicit operator override; an explicit\n`memoryguard gui ` or `memoryguard gui --workspace `\nselects a specific workspace.\nIt does not remember a previously selected project or open a folder picker.\nOn Windows, `memoryguard gui` detaches the native window from the terminal, so\nclosing PowerShell does not close the GUI.\n\nProvider-specific setup and behavior:\n\n- [Claude Code installation](docs/install-claude-code.md)\n- [Codex installation](docs/install-codex.md)\n- [Cursor installation](docs/install-cursor.md)\n\n### Stable Codex / Router binding\n\nCodex/Router binds MemoryGuard to the stable local Codex program and control\ninstallation. An account profile is an endpoint/alias, not a new memory owner:\nswitching profiles automatically discovers or repairs the profile and reuses the\nverified Agent binding and active group. Request identity remains fail-closed;\nthis does not share records across machines or with arbitrary accounts.\n\n## Upgrade\n\nMemoryGuard currently upgrades through Python's package manager:\n\n```bash\npython -m pip install --upgrade agent-memguard\nmemoryguard --version\nmemoryguard doctor\n```\n\nIf you installed the GUI extra, keep it during the upgrade:\n\n```bash\npython -m pip install --upgrade \"agent-memguard[gui]\"\n```\n\nThere is no package self-update command. The package manager is the\nauthoritative package-upgrade path; `memoryguard upgrade` below is the explicit\nworkspace migration flow, not a package updater.\n\n### Upgrade an existing V1 data home\n\nUpgrade the package, then run the verified migration. No workspace, data-home,\napply, or confirmation arguments are required for the normal user-level data\nhome:\n\n```bash\npython -m pip install --upgrade agent-memguard\nmemoryguard --version # confirms installed version\nmemoryguard upgrade\nmemoryguard doctor\n```\n\nThe command prepares V2, validates the frozen and live source evidence,\nmigrates Agent/Group control, activates only after all gates pass, and removes\nonly the backup batch belonging to that successful migration. Re-running it on\n`V2_ACTIVE` is idempotent. For a zero-write report, use:\n\n```bash\nmemoryguard upgrade --preview\n```\n\nAdvanced explicit workspace/data-home options remain available for operators\nmanaging an isolated installation. A failed gate stays non-active and preserves\nits evidence; successful activation does not keep a redundant migration backup.\n\n### Existing pre-V2 workspaces: explicit V2 cutover\n\nv0.6.0 never auto-activates an existing workspace. Upgrade the package first,\nthen use the packaged operator CLI:\n\n```bash\n# Read-only manifest status\nmemoryguard-v2 status -w .\n\n# Build a frozen-source V2 shadow and stop at V2_READY\nmemoryguard-v2 prepare -w . --apply\n\n# Activate only after the prepare result is V2_READY / ready=true\nmemoryguard-v2 activate -w . --confirm V2_ACTIVE\n```\n\nThe prepare step uses coherent SQLite online backups, preserves V1 and\n`migration-backups`, and rechecks live-source drift before READY. Activation\nperforms another fresh drift check before changing the manifest. Do not delete\nlegacy V1 data or migration backups as part of the upgrade.\n\n## Knowledge Library\n\nThe desktop console can turn a selected folder or file set into one governed\nlocal knowledge library. Source files remain where they are; MemoryGuard stores\nthe searchable index in its user data home instead of copying a runtime\ndatabase into every source project. Knowledge metadata never becomes a second\nsource-body store.\n\n| Capability | Current behavior |\n|---|---|\n| File/folder ingestion | Add a folder as a book or selected files as documents |\n| Structure | Parse documents, preserve chapter/section context, and create traceable chunks |\n| Retrieval | Full-text search, optional embeddings, and a layered knowledge graph |\n| Natural synchronization | Re-ingest changed files; a partial or failed scan does not silently remove previously indexed content |\n| Lifecycle | Move a book to the library trash, restore it, or explicitly purge its recovery snapshot |\n| Memory candidates | Preview evidence-backed candidates before accepting them into governed long-term memory |\n\nOpen the desktop console and choose **Knowledge Library**. Remote embedding or\nmodel-backed indexing is opt-in and requires explicit authorization; local\nfull-text retrieval remains available without sending source text to a remote\nprovider.\n\n### CodeGraph refresh\n\nThe first CodeGraph build is an explicit, confirmed full build. After a scope\nhas been built, each successful trusted file write can trigger an incremental\nrefresh for that scope, subject to strict source-path and active-binding\nvalidation. Unchanged content hashes are a no-op; deleted files are retired;\nthe next context receives one bounded `affected` receipt. MemoryGuard does not\nrun a daemon or watcher for this path and does not infer paths from shell or\nfree-form text.\n\n### Desktop console surfaces\n\nThe GUI has eight visible navigation entries: seven governance pages plus a\nseparate Token usage-and-savings view:\n\n1. Governance Overview\n2. Data Sources & Agents\n3. Memory Core\n4. CodeGraph\n5. Rules & Habits\n6. Conversation History\n7. Risk Signals & Governance Console\n8. Token Usage & Savings (separate from the seven governance pages)\n\nAgent lists use readable program/provider names; the underlying ID remains\navailable in the detail view. Empty data is shown as an explicit empty state.\n\n## Write and governance lifecycle\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"themeVariables\":{\"background\":\"#071521\",\"fontFamily\":\"Arial, sans-serif\",\"fontSize\":\"14px\",\"primaryTextColor\":\"#EEF4F8\",\"lineColor\":\"#557287\",\"edgeLabelBackground\":\"#071521\",\"clusterBkg\":\"#0A1A29\",\"clusterBorder\":\"#27445A\"},\"flowchart\":{\"htmlLabels\":true,\"curve\":\"basis\",\"nodeSpacing\":30,\"rankSpacing\":42,\"padding\":14}}}%%\nflowchart TD\n subgraph Intake[\"01 · INTAKE    \"]\n direction LR\n Write([\"Memory write    \"]):::entry\n Scope[\"Resolve identity
scope · audience    \"]:::core\n Validate{\"Authorized?    \"}:::decision\n Reject[\"Reject
no persistence    \"]:::danger\n Write --> Scope --> Validate\n Validate -- NO --> Reject\n end\n\n subgraph Organize[\"02 · ORGANIZE    \"]\n direction TB\n Secret{\"Sensitive?    \"}:::decision\n Quarantine[\"Quarantine
outside active set    \"]:::danger\n Compare[\"Classify · compare
governed records    \"]:::active\n Relation{\"Relationship    \"}:::decision\n New[\"NEW
create active record    \"]:::result\n Duplicate[\"DUPLICATE
merge provenance    \"]:::result\n Correction[\"CORRECTION
supersede old record    \"]:::rule\n Conflict[\"CONFLICT
preserve both sides    \"]:::danger\n\n Secret -- YES --> Quarantine\n Secret -- NO --> Compare --> Relation\n Relation --> New\n Relation --> Duplicate\n Relation --> Correction\n Relation --> Conflict\n end\n\n subgraph Govern[\"03 · GOVERN    \"]\n direction LR\n Receipt[(\"Evidence event
version receipt    \")]:::store\n Review[\"CLI or desktop review    \"]:::surface\n Action[\"Correct · merge
restore · delete    \"]:::rule\n Snapshot[\"Reversible
snapshot    \"]:::active\n Receipt --> Review --> Action --> Snapshot\n end\n\n Validate -- YES --> Secret\n Quarantine --> Receipt\n New --> Receipt\n Duplicate --> Receipt\n Correction --> Receipt\n Conflict --> Receipt\n\n classDef entry fill:#EEF4F8,stroke:#38D5C8,color:#071521,stroke-width:2.4px;\n classDef core fill:#12243A,stroke:#557287,color:#EEF4F8,stroke-width:1.5px;\n classDef decision fill:#0D3338,stroke:#38D5C8,color:#EEF4F8,stroke-width:2px;\n classDef active fill:#0D383A,stroke:#38D5C8,color:#EEF4F8,stroke-width:2px;\n classDef result fill:#12243A,stroke:#38D5C8,color:#EEF4F8,stroke-width:1.6px;\n classDef rule fill:#3B2C18,stroke:#F3B562,color:#EEF4F8,stroke-width:1.8px;\n classDef danger fill:#3A2028,stroke:#EA6A6A,color:#EEF4F8,stroke-width:1.8px;\n classDef store fill:#0B1624,stroke:#7F96A8,color:#EEF4F8,stroke-width:1.4px;\n classDef surface fill:#EEF4F8,stroke:#38D5C8,color:#071521,stroke-width:2px;\n\n style Intake fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8\n style Organize fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8\n style Govern fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8\n linkStyle default stroke:#557287,stroke-width:1.4px;\n```\n\nThe console is not an approval queue. Agents keep moving. MemoryGuard records\nthe outcome and exposes the evidence needed to correct it later.\n\n## What you can govern\n\n| Signal | Governance action |\n|---|---|\n| Duplicate or stale memory | Inspect the canonical record and supersede chain; restore an earlier version when needed |\n| Conflicting memories | Keep both visible until the conflict is resolved deliberately |\n| Secrets, tokens, or credentials | Quarantine the record so it cannot enter active shared memory |\n| Incorrect automatic organization | Correct, merge, lock, restore, or roll back with evidence |\n| Multiple coding agents | Bind agents to one shared group while preserving source identity and scope |\n| Mandatory rules | Assign rules to an Agent, project, provider, runtime role, or shared group |\n\n## Rules and history stay separate\n\nMemoryGuard deliberately keeps governed long-term memory and raw conversation\nhistory on different paths.\n\n| Surface | Purpose | Context behavior |\n|---|---|---|\n| **Rules and habits** | Preferences, procedures, corrections, facts, projects, and scoped mandatory rules | Mandatory rules use an independent char/token budget after scope, exclude, conflict, and semantic dedup. Effective count above 20 is a health warning, not a hard block; storage is not capped by count. Sensitive, corrupt, per-item oversize, and aggregate overflow still fail closed with no silent truncation. Ordinary records are recalled when relevant |\n| **Conversation history** | Local raw-evidence archive with owner and shared-group access controls | Never enters bootstrap automatically; raw text is read only through explicit history tools |\n| **Neuron graph** | Navigation and governance over memory, rules, projects, agents, and sessions | History nodes contain safe metadata and summaries, not raw chat content |\n\nHistory retrieval is progressive: search results, then a bounded timeline, then\nan explicitly selected turn or session. Extracting from history creates a\npreview first; it does not silently write a long-term memory.\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"themeVariables\":{\"background\":\"#071521\",\"fontFamily\":\"Arial, sans-serif\",\"fontSize\":\"14px\",\"primaryTextColor\":\"#EEF4F8\",\"lineColor\":\"#557287\",\"edgeLabelBackground\":\"#071521\",\"clusterBkg\":\"#0A1A29\",\"clusterBorder\":\"#27445A\"},\"flowchart\":{\"htmlLabels\":true,\"curve\":\"basis\",\"nodeSpacing\":30,\"rankSpacing\":42,\"padding\":14}}}%%\nflowchart LR\n subgraph HistoryPath[\"CONVERSATION EVIDENCE    \"]\n direction TB\n Archive[(\"Raw local history    \")]:::historyStore\n Search[\"Search summaries    \"]:::history\n Timeline[\"Bounded timeline    \"]:::history\n Read[\"Explicit turn or session    \"]:::history\n Preview[\"Evidence-backed
extraction preview    \"]:::history\n Confirm[\"Explicit acceptance    \"]:::surface\n Isolation[\"NO AUTOMATIC
BOOTSTRAP PATH    \"]:::barrier\n\n Archive --> Search --> Timeline --> Read --> Preview --> Confirm\n Archive -.-> Isolation\n end\n\n subgraph GovernedMemory[\"GOVERNED LONG-TERM MEMORY    \"]\n direction TB\n Mandatory[\"Scoped mandatory rules    \"]:::rule\n Assignments[\"Agent · project
role · group scope    \"]:::core\n RulePack[\"Mandatory-rule
budget    \"]:::budget\n Ordinary[\"Facts · preferences
projects · procedures    \"]:::memory\n Recall[\"Task-relevant
recall budget    \"]:::budget\n Context[\"BOUNDED CONTEXT PACKET    \"]:::context\n\n Mandatory --> Assignments --> RulePack --> Context\n Ordinary --> Recall --> Context\n end\n\n HistoryPath ==>|GOVERNED WRITE    | GovernedMemory\n\n classDef rule fill:#3B2C18,stroke:#F3B562,color:#EEF4F8,stroke-width:1.8px;\n classDef core fill:#12243A,stroke:#557287,color:#EEF4F8,stroke-width:1.4px;\n classDef memory fill:#0D383A,stroke:#38D5C8,color:#EEF4F8,stroke-width:1.8px;\n classDef budget fill:#12243A,stroke:#38D5C8,color:#EEF4F8,stroke-width:1.6px;\n classDef context fill:#EEF4F8,stroke:#38D5C8,color:#071521,stroke-width:2.4px;\n classDef history fill:#102F45,stroke:#73C7F5,color:#EEF4F8,stroke-width:1.6px;\n classDef historyStore fill:#102436,stroke:#73C7F5,color:#EEF4F8,stroke-width:1.6px;\n classDef surface fill:#EEF4F8,stroke:#73C7F5,color:#071521,stroke-width:2px;\n classDef barrier fill:#3A2028,stroke:#EA6A6A,color:#EEF4F8,stroke-width:2px;\n\n style GovernedMemory fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8\n style HistoryPath fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8\n linkStyle default stroke:#557287,stroke-width:1.4px;\n```\n\n## Supported hosts\n\n| Host | Integration | Current boundary |\n|---|---|---|\n| Claude Code | Global MCP binding, redirect rules, user-level lifecycle Hook | Verified takeover path |\n| Codex | Global MCP binding, redirect rules, user-level lifecycle Hook | Verified takeover path |\n| Cursor | Global MCP binding, redirect rules, user-level lifecycle Hook | Verified takeover path |\n| TRAE | MCP binding and redirect rules | No verified Hook seam; reported as a fallback instead of full takeover |\n\nProvider status is reported honestly as redirected, observed, operational, or\nunsupported. MemoryGuard does not claim it can disable every host's native\nmemory when the host exposes no reliable integration point.\n\n## Architecture\n\n| Layer | Responsibility |\n|---|---|\n| **Evidence & Content** | Authorized sources, immutable evidence, content-addressed blobs/occurrences, source manifests, and conversation archives |\n| **Memory & Rules** | Scoped memory atoms, revisions, bindings, rule definitions, decisions, evidence links, and compensating governance operations |\n| **Runtime & Projection** | Bounded working context, scenario/profile projections, CodeGraph, Assets, and Skills metadata |\n| **Cutover & Governance** | Four-state manifest, native MCP/CLI/GUI/Hook routing, Reference Audit, maintenance, provider adapters, and rollback evidence |\n\nV2 uses separate authoritative SQLite domains rather than one shared-memory\ndatabase. The runtime reads and writes V2 only after the manifest reaches\n`V2_ACTIVE`; `V2_BUILDING` and `V2_READY` never silently fall back or dual-write.\nEvidence remains traceable without being treated as automatically trusted memory.\n\n## Privacy and safety\n\n- MemoryGuard runs as a local MCP stdio server.\n- All governed data stays local unless you explicitly authorize a remote model\n or embedding operation. Optional usage telemetry is local-only: its measured\n host token events and deterministic conversion events are stored under\n `.memoryguard/usage_telemetry.sqlite`; it does not upload data. Token savings\n are estimates based on MemoryGuard deterministic units, not a provider billing\n statement. Hosts without token reporting remain unsupported in the measured\n columns.\n- The Knowledge Library database uses `MEMORYGUARD_HOME` or the platform user\n data directory, so a selected source folder does not receive its own\n knowledge database.\n- V2 authoritative workspace state is separated under `.memoryguard/` into\n explicit Memory, Rules, Evidence, Content, Runtime, Projection, Assets,\n CodeGraph, Skills, and System domains; History, Source, Binding, and Group\n control are V2-native surfaces. Legacy V1 artifacts are preserved as local\n rollback/audit evidence after cutover and are no longer the active V2 runtime\n write path; only `memoryguard.migration` may read them.\n- Source scanning is read-only by default.\n- Mutating governance paths use validation, explicit scope, provenance, and\n reversible state.\n- Quarantined records stay outside active shared memory.\n- Raw conversation history is never injected into bootstrap automatically.\n- Shared-group history access follows current active membership and does not\n grant deletion rights over another Agent's source.\n\n## CLI\n\nThe installed `memoryguard` command exposes these top-level operations:\n\n| Command | Purpose |\n|---|---|\n| `audit [path]` | Run a read-only audit and generate a report |\n| `open [path]` | Open the latest interactive report |\n| `explain ` | Explain evidence and risk for a finding |\n| `source ` | List, add, remove, or preview authorized sources |\n| `scan` | Scan authorized sources and build the coverage ledger |\n| `doctor` | Diagnose V2 manifest, domain availability, and native coverage |\n| `mcp-status` | Inspect V2 MCP/backend health; tenant counts require a bound Agent scope |\n| `hooks ` | Install, inspect, pause, repair, or remove host Hooks |\n| `provider ` | Inspect or repair global provider integrations |\n| `storage audit|report` | Run read-only V2 Reference Audit and per-domain SQLite health reports |\n| `storage sweep|compact` | Run guarded V2 maintenance; physical changes require ACTIVE state, lease, generation, and safety proofs |\n| `groups ` | Inspect governed group state |\n| `gui [path]` | Launch the interactive governance console |\n| `desktop` | Launch the trusted desktop executor |\n\nThe old V1 `plan`, `apply`, `verify`, `undo`, `import`, and `gc` workflows may\nremain parseable as explicit retired compatibility surfaces, but are not a V1\nruntime path. Under `V2_ACTIVE` they return a stable retired result instead of\nwriting through a legacy store. Legacy data input is accepted only by the\nexplicit `memoryguard.migration` upgrade flow.\n\nRun `memoryguard --help` or `memoryguard --help` for the live command\nreference.\n\n## MCP API\n\nThe default MCP discovery surface is intentionally compact. New MCP clients\nreceive these nine day-to-day tools through `tools/list`:\n\n| Tool | Purpose |\n|---|---|\n| `memoryguard_context_bootstrap` | Load bounded mandatory rules and relevant memory context |\n| `memoryguard_memory_search` | Search governed memories by query, lifecycle status, and bounded limit. `kind` is not an MCP search filter; semantic duplicate/conflict checks are separate advanced governance. |\n| `memoryguard_memory_read` | Read one governed memory |\n| `memoryguard_memory_write` | Write and organize a governed memory |\n| `memoryguard_memory_update` | Update the body, kind, recall policy, or priority of one known memory. It does not change lifecycle status or restore deleted records; restoration is a GUI governance action. |\n| `memoryguard_memory_delete` | Soft-delete a governed memory |\n| `memoryguard_memory_status` | Inspect shared-memory status |\n| `memoryguard_audit` | Run a read-only local governance audit |\n| `memoryguard_explain` | Explain one audit finding and its evidence |\n\nAdvanced governance remains available through the GUI and CLI: rule lifecycle,\nbindings and shared groups, source scanning, CodeGraph, knowledge and history\nreview, provider controls, external MCP import, and maintenance operations.\nExisting advanced MCP names remain callable for compatibility when an installed\nclient invokes an exact name, but they are not returned by the default\n`tools/list`. This reduces discovery/schema overhead without removing those\ngovernance capabilities.\n\nThe underlying compatibility catalog also covers:\n\n- governed memory read, search, write, update, delete, and status;\n- bounded context bootstrap with mandatory-rule isolation;\n- rule creation, feedback, merge governance, undo, and scope statistics;\n- Agent binding and shared-group inspection;\n- source scanning, graph projection, import previews, and build planning;\n- external MCP discovery and import;\n- document extraction previews and candidate acceptance;\n- conversation-history search, timeline, explicit read, export, deletion, and\n extraction preview;\n- provider installation and host-agent enrichment.\n\nUse MCP `tools/list` as the source of truth for the exact tool set supported by\nthe installed version.\n\n## Project links\n\n- [PyPI package](https://pypi.org/project/agent-memguard/)\n- [GitHub releases](https://github.com/irisxc4/memoryguard/releases)\n- [Changelog](CHANGELOG.md)\n- [v0.7.11 release note](docs/releases/v0.7.11.md)\n- [v0.7.9 release record](docs/releases/v0.7.9.md)\n- [v0.7.8 release record](docs/releases/v0.7.8.md)\n- [v0.7.7 release record](docs/releases/v0.7.7.md)\n- [v0.7.6 release record](docs/releases/v0.7.6.md)\n- [v0.7.5 release record](docs/releases/v0.7.5.md)\n- [v0.7.4 release record](docs/releases/v0.7.4.md)\n- [v0.7.3 release record](docs/releases/v0.7.3.md)\n- [v0.7.2 release record](docs/releases/v0.7.2.md)\n- [v0.7.1 release record](docs/releases/v0.7.1.md)\n- [v0.7.0 release gate](docs/releases/v0.7.0.md)\n- [Memory continuity and lossless storage spec](docs/memory-continuity-storage-spec-v1.md)\n- [Privacy policy](PRIVACY.md)\n- [Terms of use](TERMS.md)\n- [Contributing guide](CONTRIBUTING.md)\n- [Contributor License Agreement](CLA.md)\n- [Issue tracker](https://github.com/irisxc4/memoryguard/issues)\n\n## Roadmap\n\n- **Release history:** v0.7.9 consolidates canonical governance, local-only token evidence, readable multi-agent governance, and public distribution through GitHub, PyPI, and the official MCP Registry. v0.7.8 records the preceding governance, telemetry, and Codex runtime work; v0.7.7 makes bare provider repair safe in a verified, uniquely bound control home and aligns installed Codex MCP/Hook repairs to the current interpreter while preserving Agent and shared-group identity. v0.7.6 makes Codex Hook/MCP runtime selection consistent through one immutable snapshot, shortens Hook state lock windows, and keeps bootstrap success/failure state honest with explicit mandatory-overflow fail-closed handling. Earlier release records retain the detailed v0.7.5 conflict-review, v0.7.4 canonical-governance, v0.7.3 shared-history, and v0.7.2 write/read and Codex lifecycle changes. The\n v0.7.1 V2-only migration and desktop lifecycle work remains documented as\n historical release context.\n- **Acceptance boundary:** the Graphify evidence is the focused `3 / 3` result\n plus the real full-repository export/projection described above. It does not\n claim that upstream Graphify's full-repository test suite passed.\n- **Next after release:** broader CodeGraph/Skills ingestion, more operator-friendly\n maintenance reports, and additional migration observability. Long-term records\n are not retired merely because they are old.\n- **Later:** team and enterprise capabilities only after validated demand.\n\n## Contributing\n\nIssues and pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md)\nbefore submitting a change. Pull requests require agreement to the\n[CLA](CLA.md).\n\n## License\n\n[MIT](LICENSE)\n", "bytes": 35475, "sha": "c7ea558e3d9bc386b78f8e5f6ff2bec2e4a23504cfe1e9a95869f54520aa077e", "repo_slug": "irisxc4/memoryguard", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_irisxc4_memoryguard_97fcf52f/readme" }