memoryguard

MemoryGuard

Governed shared memory for coding agents.

Local-first MCP memory with automatic organization, scoped rules, evidence, and rollback.

> Let agents write without turning shared memory into an unreviewed pile.

> MemoryGuard organizes each write, preserves the evidence behind changes, and

> keeps governance decisions reversible.

>

> **No account. No remote server. No remote telemetry. Local-only usage telemetry

> is optional and stores bounded, privacy-preserving aggregates locally.**

·

·

·

·

·

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

What's New in v0.7.11

v0.7.11 is a public documentation and discovery consistency release. Runtime

behavior summarized here originates in v0.7.9:

• Canonical memory and rule governance: related rules, habits, and memories

converge through one canonical read/write path while evidence, source links,

graph branches, supersede history, conflict review, and settlement remain

auditable and reversible.

• Readable multi-agent governance: verified program identities, readable

labels, safe family icons, shared-group scope, risk explanations, stale-conflict

closure, seven governance pages, and a separate Token usage-and-savings entry

keep daily governance understandable.

• Local usage and savings view: the Token page shows local MCP conversion

events and seven-/thirty-day estimated baseline-versus-delivered units.

Provider token measurements are used only when reported (currently Codex and

Grok); Claude, Cursor, and Trae remain explicitly unsupported. No conversation

body, account, path, or instance identifier is stored.

• Codex lifecycle and runtime alignment: terminal-thread evidence gates

reclamation of Codex-owned leaked cohorts; ordinary turns remain resumable.

Installed repair aligns MCP and lifecycle Hooks to the current interpreter

while preserving Agent/shared-group identity and fail-closed boundaries.

• Evidence and discovery: `scripts/benchmark_usage_telemetry.py` documents

reproducible seven-/thirty-day local measurements with explicit coverage and

no-sample semantics. Releases are published through GitHub OIDC to

GitHub Releases,

PyPI, and the official MCP

Registry. Verify current package and registry status through those live

records. No Glama score or third-party directory listing is implied.

See the v0.7.11 release note and

release history.

Earlier release details are kept in the Changelog and

GitHub release records.

Token evidence and demo

Run the benchmark only against an authorized local workspace:

python scripts/benchmark_usage_telemetry.py --workspace . --window-days 7 --sync

Read the benchmark guide for measured,

estimated, derived, and unsupported semantics. Use [the demo recording

checklist](docs/benchmarks/demo-script.md) for a sanitized walkthrough. The

repository's synthetic graph artwork is not a live product capture; it is not

evidence of usage or savings.

Major V2 refactor in v0.6.0

v0.6.0 was a production data-plane refactor, not a storage-only upgrade:

• Authoritative V2 domains: Memory, Rules, Evidence, Content, Runtime, Projection, Assets, CodeGraph, Skills, and System state are separated into explicit SQLite domains with governed boundaries.
• 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.
• 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.
• 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.
• 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.
• Operational evidence: Reference Audit, per-domain SQLite health, guarded maintenance, rollback evidence, and safe unbound diagnostics are part of readiness and operations.

Why MemoryGuard

Persistent memory solves storage. It does not solve governance.

When several coding agents write into the same context, records become

duplicated, stale, contradictory, over-broad, or unsafe to reuse. MemoryGuard

sits between coding agents and their shared memory to keep that context usable.

System architecture

%%{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}}}%%
flowchart TB
    Hosts["CODING-AGENT HOSTSClaude Code · Codex · Cursor · TRAE    "]:::host
    Gateway["LOCAL INTEGRATIONMCP stdio · redirect rules · lifecycle hooks    "]:::gateway

    subgraph Core["GOVERNANCE CORE    "]
        direction LR
        Identity["TRUSTidentity · scope    "]:::core
        MemoryAPI["MEMORYgoverned I/O    "]:::active
        Rules["RULESscope · assignment    "]:::rule
        HistoryAPI["HISTORYsearch · timeline    "]:::history
        Security["SAFETYvalidate · quarantine    "]:::danger

        Identity --> MemoryAPI
        Identity --> Rules
        Identity --> HistoryAPI
        MemoryAPI --> Security
    end

    subgraph Stores["LOCAL GOVERNED STORES    "]
        direction LR
        SharedDB[("V2 DOMAIN STORESMemory · Rules · Evidence · Content    ")]:::store
        HistoryDB[("HISTORY STOREisolated conversations    ")]:::historyStore
        AuditDB[("RECOVERY STOREversions · receipts · backups    ")]:::store
    end

    Bootstrap["BOUNDED CONTEXT BOOTSTRAPmandatory rule pack · relevant recall    "]:::bootstrap
    Control["HUMAN CONTROLCLI · desktop governance console    "]:::surface

    Hosts --> Gateway --> Identity
    MemoryAPI --> SharedDB
    Rules --> SharedDB
    HistoryAPI --> HistoryDB
    Security --> AuditDB
    SharedDB --> Bootstrap
    Control --> Identity

    classDef host fill:#12243A,stroke:#38D5C8,color:#EEF4F8,stroke-width:1.4px;
    classDef gateway fill:#0D3338,stroke:#38D5C8,color:#EEF4F8,stroke-width:2.4px;
    classDef core fill:#12243A,stroke:#557287,color:#EEF4F8,stroke-width:1.4px;
    classDef active fill:#0D383A,stroke:#38D5C8,color:#EEF4F8,stroke-width:2px;
    classDef rule fill:#3B2C18,stroke:#F3B562,color:#EEF4F8,stroke-width:1.8px;
    classDef history fill:#102F45,stroke:#73C7F5,color:#EEF4F8,stroke-width:1.8px;
    classDef danger fill:#3A2028,stroke:#EA6A6A,color:#EEF4F8,stroke-width:1.8px;
    classDef bootstrap fill:#EEF4F8,stroke:#38D5C8,color:#071521,stroke-width:2.4px;
    classDef store fill:#0B1624,stroke:#7F96A8,color:#EEF4F8,stroke-width:1.4px;
    classDef historyStore fill:#102436,stroke:#73C7F5,color:#EEF4F8,stroke-width:1.4px;
    classDef surface fill:#EEF4F8,stroke:#38D5C8,color:#071521,stroke-width:2px;

    style Core fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8
    style Stores fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8
    linkStyle default stroke:#557287,stroke-width:1.4px;

Quick start

MCP Registry metadata

This package exposes a local stdio MCP server as `io.github.irisxc4/memoryguard`.

Registry metadata is kept in `server.json`, and the marker above

ships with the PyPI package README. Releases are published through GitHub OIDC

to PyPI and the official MCP Registry. Verify the current package version and

the Registry entry's active/latest state through their live public records.

1. Install

python -m pip install agent-memguard

For the desktop governance console:

python -m pip install "agent-memguard[gui]"

2. Authorize the current project

memoryguard source add .

3. Connect or repair your coding agent

Global 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.

# Repair one provider
memoryguard provider repair claude
memoryguard provider repair codex
memoryguard provider repair cursor
memoryguard provider repair trae

# Repair every detected provider
memoryguard provider repair all

Restart the host after installation, then verify the integration:

memoryguard doctor
memoryguard mcp-status
memoryguard hooks status --provider all

Launch the desktop console:

memoryguard gui

`memoryguard-gui .` remains available for desktop shortcuts. A bare

`memoryguard gui` always opens the canonical user-level control directory

(default `%LOCALAPPDATA%\MemoryGuard` on Windows), so running it from a project

or from `C:\Windows\System32` cannot silently switch databases.

`MEMORYGUARD_WORKSPACE` is an explicit operator override; an explicit

`memoryguard gui ` or `memoryguard gui --workspace `

selects a specific workspace.

It does not remember a previously selected project or open a folder picker.

On Windows, `memoryguard gui` detaches the native window from the terminal, so

closing PowerShell does not close the GUI.

Provider-specific setup and behavior:

• Claude Code installation
• Codex installation
• Cursor installation

Stable Codex / Router binding

Codex/Router binds MemoryGuard to the stable local Codex program and control

installation. An account profile is an endpoint/alias, not a new memory owner:

switching profiles automatically discovers or repairs the profile and reuses the

verified Agent binding and active group. Request identity remains fail-closed;

this does not share records across machines or with arbitrary accounts.

Upgrade

MemoryGuard currently upgrades through Python's package manager:

python -m pip install --upgrade agent-memguard
memoryguard --version
memoryguard doctor

If you installed the GUI extra, keep it during the upgrade:

python -m pip install --upgrade "agent-memguard[gui]"

There is no package self-update command. The package manager is the

authoritative package-upgrade path; `memoryguard upgrade` below is the explicit

workspace migration flow, not a package updater.

Upgrade an existing V1 data home

Upgrade the package, then run the verified migration. No workspace, data-home,

apply, or confirmation arguments are required for the normal user-level data

home:

python -m pip install --upgrade agent-memguard
memoryguard --version                    # confirms installed version
memoryguard upgrade
memoryguard doctor

The command prepares V2, validates the frozen and live source evidence,

migrates Agent/Group control, activates only after all gates pass, and removes

only the backup batch belonging to that successful migration. Re-running it on

`V2_ACTIVE` is idempotent. For a zero-write report, use:

memoryguard upgrade --preview

Advanced explicit workspace/data-home options remain available for operators

managing an isolated installation. A failed gate stays non-active and preserves

its evidence; successful activation does not keep a redundant migration backup.

Existing pre-V2 workspaces: explicit V2 cutover

v0.6.0 never auto-activates an existing workspace. Upgrade the package first,

then use the packaged operator CLI:

# Read-only manifest status
memoryguard-v2 status -w .

# Build a frozen-source V2 shadow and stop at V2_READY
memoryguard-v2 prepare -w . --apply

# Activate only after the prepare result is V2_READY / ready=true
memoryguard-v2 activate -w . --confirm V2_ACTIVE

The prepare step uses coherent SQLite online backups, preserves V1 and

`migration-backups`, and rechecks live-source drift before READY. Activation

performs another fresh drift check before changing the manifest. Do not delete

legacy V1 data or migration backups as part of the upgrade.

Knowledge Library

The desktop console can turn a selected folder or file set into one governed

local knowledge library. Source files remain where they are; MemoryGuard stores

the searchable index in its user data home instead of copying a runtime

database into every source project. Knowledge metadata never becomes a second

source-body store.

Open the desktop console and choose Knowledge Library. Remote embedding or

model-backed indexing is opt-in and requires explicit authorization; local

full-text retrieval remains available without sending source text to a remote

provider.

CodeGraph refresh

The first CodeGraph build is an explicit, confirmed full build. After a scope

has been built, each successful trusted file write can trigger an incremental

refresh for that scope, subject to strict source-path and active-binding

validation. Unchanged content hashes are a no-op; deleted files are retired;

the next context receives one bounded `affected` receipt. MemoryGuard does not

run a daemon or watcher for this path and does not infer paths from shell or

free-form text.

Desktop console surfaces

The GUI has eight visible navigation entries: seven governance pages plus a

separate Token usage-and-savings view:

1. Governance Overview

2. Data Sources & Agents

3. Memory Core

4. CodeGraph

5. Rules & Habits

6. Conversation History

7. Risk Signals & Governance Console

8. Token Usage & Savings (separate from the seven governance pages)

Agent lists use readable program/provider names; the underlying ID remains

available in the detail view. Empty data is shown as an explicit empty state.

Write and governance lifecycle

%%{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}}}%%
flowchart TD
    subgraph Intake["01 · INTAKE    "]
        direction LR
        Write(["Memory write    "]):::entry
        Scope["Resolve identityscope · audience    "]:::core
        Validate{"Authorized?    "}:::decision
        Reject["Rejectno persistence    "]:::danger
        Write --> Scope --> Validate
        Validate -- NO --> Reject
    end

    subgraph Organize["02 · ORGANIZE    "]
        direction TB
        Secret{"Sensitive?    "}:::decision
        Quarantine["Quarantineoutside active set    "]:::danger
        Compare["Classify · comparegoverned records    "]:::active
        Relation{"Relationship    "}:::decision
        New["NEWcreate active record    "]:::result
        Duplicate["DUPLICATEmerge provenance    "]:::result
        Correction["CORRECTIONsupersede old record    "]:::rule
        Conflict["CONFLICTpreserve both sides    "]:::danger

        Secret -- YES --> Quarantine
        Secret -- NO --> Compare --> Relation
        Relation --> New
        Relation --> Duplicate
        Relation --> Correction
        Relation --> Conflict
    end

    subgraph Govern["03 · GOVERN    "]
        direction LR
        Receipt[("Evidence eventversion receipt    ")]:::store
        Review["CLI or desktop review    "]:::surface
        Action["Correct · mergerestore · delete    "]:::rule
        Snapshot["Reversiblesnapshot    "]:::active
        Receipt --> Review --> Action --> Snapshot
    end

    Validate -- YES --> Secret
    Quarantine --> Receipt
    New --> Receipt
    Duplicate --> Receipt
    Correction --> Receipt
    Conflict --> Receipt

    classDef entry fill:#EEF4F8,stroke:#38D5C8,color:#071521,stroke-width:2.4px;
    classDef core fill:#12243A,stroke:#557287,color:#EEF4F8,stroke-width:1.5px;
    classDef decision fill:#0D3338,stroke:#38D5C8,color:#EEF4F8,stroke-width:2px;
    classDef active fill:#0D383A,stroke:#38D5C8,color:#EEF4F8,stroke-width:2px;
    classDef result fill:#12243A,stroke:#38D5C8,color:#EEF4F8,stroke-width:1.6px;
    classDef rule fill:#3B2C18,stroke:#F3B562,color:#EEF4F8,stroke-width:1.8px;
    classDef danger fill:#3A2028,stroke:#EA6A6A,color:#EEF4F8,stroke-width:1.8px;
    classDef store fill:#0B1624,stroke:#7F96A8,color:#EEF4F8,stroke-width:1.4px;
    classDef surface fill:#EEF4F8,stroke:#38D5C8,color:#071521,stroke-width:2px;

    style Intake fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8
    style Organize fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8
    style Govern fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8
    linkStyle default stroke:#557287,stroke-width:1.4px;

The console is not an approval queue. Agents keep moving. MemoryGuard records

the outcome and exposes the evidence needed to correct it later.

What you can govern

Rules and history stay separate

MemoryGuard deliberately keeps governed long-term memory and raw conversation

history on different paths.

History retrieval is progressive: search results, then a bounded timeline, then

an explicitly selected turn or session. Extracting from history creates a

preview first; it does not silently write a long-term memory.

%%{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}}}%%
flowchart LR
    subgraph HistoryPath["CONVERSATION EVIDENCE    "]
        direction TB
        Archive[("Raw local history    ")]:::historyStore
        Search["Search summaries    "]:::history
        Timeline["Bounded timeline    "]:::history
        Read["Explicit turn or session    "]:::history
        Preview["Evidence-backedextraction preview    "]:::history
        Confirm["Explicit acceptance    "]:::surface
        Isolation["NO AUTOMATICBOOTSTRAP PATH    "]:::barrier

        Archive --> Search --> Timeline --> Read --> Preview --> Confirm
        Archive -.-> Isolation
    end

    subgraph GovernedMemory["GOVERNED LONG-TERM MEMORY    "]
        direction TB
        Mandatory["Scoped mandatory rules    "]:::rule
        Assignments["Agent · projectrole · group scope    "]:::core
        RulePack["Mandatory-rulebudget    "]:::budget
        Ordinary["Facts · preferencesprojects · procedures    "]:::memory
        Recall["Task-relevantrecall budget    "]:::budget
        Context["BOUNDED CONTEXT PACKET    "]:::context

        Mandatory --> Assignments --> RulePack --> Context
        Ordinary --> Recall --> Context
    end

    HistoryPath ==>|GOVERNED WRITE    | GovernedMemory

    classDef rule fill:#3B2C18,stroke:#F3B562,color:#EEF4F8,stroke-width:1.8px;
    classDef core fill:#12243A,stroke:#557287,color:#EEF4F8,stroke-width:1.4px;
    classDef memory fill:#0D383A,stroke:#38D5C8,color:#EEF4F8,stroke-width:1.8px;
    classDef budget fill:#12243A,stroke:#38D5C8,color:#EEF4F8,stroke-width:1.6px;
    classDef context fill:#EEF4F8,stroke:#38D5C8,color:#071521,stroke-width:2.4px;
    classDef history fill:#102F45,stroke:#73C7F5,color:#EEF4F8,stroke-width:1.6px;
    classDef historyStore fill:#102436,stroke:#73C7F5,color:#EEF4F8,stroke-width:1.6px;
    classDef surface fill:#EEF4F8,stroke:#73C7F5,color:#071521,stroke-width:2px;
    classDef barrier fill:#3A2028,stroke:#EA6A6A,color:#EEF4F8,stroke-width:2px;

    style GovernedMemory fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8
    style HistoryPath fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8
    linkStyle default stroke:#557287,stroke-width:1.4px;

Supported hosts

Provider status is reported honestly as redirected, observed, operational, or

unsupported. MemoryGuard does not claim it can disable every host's native

memory when the host exposes no reliable integration point.

Architecture

V2 uses separate authoritative SQLite domains rather than one shared-memory

database. The runtime reads and writes V2 only after the manifest reaches

`V2_ACTIVE`; `V2_BUILDING` and `V2_READY` never silently fall back or dual-write.

Evidence remains traceable without being treated as automatically trusted memory.

Privacy and safety

• MemoryGuard runs as a local MCP stdio server.
• All governed data stays local unless you explicitly authorize a remote model

or embedding operation. Optional usage telemetry is local-only: its measured

host token events and deterministic conversion events are stored under

`.memoryguard/usage_telemetry.sqlite`; it does not upload data. Token savings

are estimates based on MemoryGuard deterministic units, not a provider billing

statement. Hosts without token reporting remain unsupported in the measured

columns.

• The Knowledge Library database uses `MEMORYGUARD_HOME` or the platform user

data directory, so a selected source folder does not receive its own

knowledge database.

• V2 authoritative workspace state is separated under `.memoryguard/` into

explicit Memory, Rules, Evidence, Content, Runtime, Projection, Assets,

CodeGraph, Skills, and System domains; History, Source, Binding, and Group

control are V2-native surfaces. Legacy V1 artifacts are preserved as local

rollback/audit evidence after cutover and are no longer the active V2 runtime

write path; only `memoryguard.migration` may read them.

• Source scanning is read-only by default.
• Mutating governance paths use validation, explicit scope, provenance, and

reversible state.

• Quarantined records stay outside active shared memory.
• Raw conversation history is never injected into bootstrap automatically.
• Shared-group history access follows current active membership and does not

grant deletion rights over another Agent's source.

CLI

The installed `memoryguard` command exposes these top-level operations:

The old V1 `plan`, `apply`, `verify`, `undo`, `import`, and `gc` workflows may

remain parseable as explicit retired compatibility surfaces, but are not a V1

runtime path. Under `V2_ACTIVE` they return a stable retired result instead of

writing through a legacy store. Legacy data input is accepted only by the

explicit `memoryguard.migration` upgrade flow.

Run `memoryguard --help` or `memoryguard --help` for the live command

reference.

MCP API

The MCP server exposes tools for:

• governed memory read, search, write, update, delete, and status;
• bounded context bootstrap with mandatory-rule isolation;
• rule creation, feedback, merge governance, undo, and scope statistics;
• Agent binding and shared-group inspection;
• source scanning, graph projection, import previews, and build planning;
• external MCP discovery and import;
• document extraction previews and candidate acceptance;
• conversation-history search, timeline, explicit read, export, deletion, and

extraction preview;

• provider installation and host-agent enrichment.

Use MCP `tools/list` as the source of truth for the exact tool set supported by

the installed version.

Project links

• PyPI package
• GitHub releases
• Changelog
• v0.7.11 release note
• v0.7.9 release record
• v0.7.8 release record
• v0.7.7 release record
• v0.7.6 release record
• v0.7.5 release record
• v0.7.4 release record
• v0.7.3 release record
• v0.7.2 release record
• v0.7.1 release record
• v0.7.0 release gate
• Memory continuity and lossless storage spec
• Privacy policy
• Terms of use
• Contributing guide
• Contributor License Agreement
• Issue tracker

Roadmap

• 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

v0.7.1 V2-only migration and desktop lifecycle work remains documented as

historical release context.

• Acceptance boundary: the Graphify evidence is the focused `3 / 3` result

plus the real full-repository export/projection described above. It does not

claim that upstream Graphify's full-repository test suite passed.

• Next after release: broader CodeGraph/Skills ingestion, more operator-friendly

maintenance reports, and additional migration observability. Long-term records

are not retired merely because they are old.

• Later: team and enterprise capabilities only after validated demand.

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md

before submitting a change. Pull requests require agreement to the

CLA.

License

MIT