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 telemetry. Memory stays local.

Quick start · Upgrade · Architecture · Supported hosts · Privacy and safety

Animated MemoryGuard neuron graph with governed memory categories and signals moving through the local projection

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

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.

Without governance	With MemoryGuard
Notes accumulate without a canonical state	Writes are classified, deduplicated, superseded, or surfaced as conflicts
A correction silently destroys the old value	Evidence and supersede chains preserve what changed and why
Tokens and credentials can remain active	Sensitive-looking content is quarantined from active memory
Every write needs manual approval	Agents write normally; people review exceptions and outcomes
Raw chat logs leak into future context	Conversation history remains a separate, explicitly read evidence archive

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 HOSTS<br/>Claude Code · Codex · Cursor · TRAE&nbsp;&nbsp;&nbsp;&nbsp;"]:::host
    Gateway["LOCAL INTEGRATION<br/>MCP stdio · redirect rules · lifecycle hooks&nbsp;&nbsp;&nbsp;&nbsp;"]:::gateway

    subgraph Core["GOVERNANCE CORE&nbsp;&nbsp;&nbsp;&nbsp;"]
        direction LR
        Identity["TRUST<br/>identity · scope&nbsp;&nbsp;&nbsp;&nbsp;"]:::core
        MemoryAPI["MEMORY<br/>governed I/O&nbsp;&nbsp;&nbsp;&nbsp;"]:::active
        Rules["RULES<br/>scope · assignment&nbsp;&nbsp;&nbsp;&nbsp;"]:::rule
        HistoryAPI["HISTORY<br/>search · timeline&nbsp;&nbsp;&nbsp;&nbsp;"]:::history
        Security["SAFETY<br/>validate · quarantine&nbsp;&nbsp;&nbsp;&nbsp;"]:::danger

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

    subgraph Stores["LOCAL GOVERNED STORES&nbsp;&nbsp;&nbsp;&nbsp;"]
        direction LR
        SharedDB[("MEMORY STORE<br/>records · rules · evidence&nbsp;&nbsp;&nbsp;&nbsp;")]:::store
        HistoryDB[("HISTORY STORE<br/>isolated conversations&nbsp;&nbsp;&nbsp;&nbsp;")]:::historyStore
        AuditDB[("RECOVERY STORE<br/>versions · receipts · backups&nbsp;&nbsp;&nbsp;&nbsp;")]:::store
    end

    Bootstrap["BOUNDED CONTEXT BOOTSTRAP<br/>mandatory rule pack · relevant recall&nbsp;&nbsp;&nbsp;&nbsp;"]:::bootstrap
    Control["HUMAN CONTROL<br/>CLI · desktop governance console&nbsp;&nbsp;&nbsp;&nbsp;"]:::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

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 your coding agent

Run one provider installer:

# Claude Code
python -m memoryguard.provider_adapters install claude

# Codex
python -m memoryguard.provider_adapters install codex

# Cursor
python -m memoryguard.provider_adapters install cursor

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 .

Provider-specific setup and behavior:

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 separate memoryguard update self-update command yet. The package manager is the authoritative upgrade path, while MemoryGuard's schema migrations run when the upgraded application opens its local stores.

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&nbsp;&nbsp;&nbsp;&nbsp;"]
        direction LR
        Write(["Memory write&nbsp;&nbsp;&nbsp;&nbsp;"]):::entry
        Scope["Resolve identity<br/>scope · audience&nbsp;&nbsp;&nbsp;&nbsp;"]:::core
        Validate{"Authorized?&nbsp;&nbsp;&nbsp;&nbsp;"}:::decision
        Reject["Reject<br/>no persistence&nbsp;&nbsp;&nbsp;&nbsp;"]:::danger
        Write --> Scope --> Validate
        Validate -- NO --> Reject
    end

    subgraph Organize["02 · ORGANIZE&nbsp;&nbsp;&nbsp;&nbsp;"]
        direction TB
        Secret{"Sensitive?&nbsp;&nbsp;&nbsp;&nbsp;"}:::decision
        Quarantine["Quarantine<br/>outside active set&nbsp;&nbsp;&nbsp;&nbsp;"]:::danger
        Compare["Classify · compare<br/>governed records&nbsp;&nbsp;&nbsp;&nbsp;"]:::active
        Relation{"Relationship&nbsp;&nbsp;&nbsp;&nbsp;"}:::decision
        New["NEW<br/>create active record&nbsp;&nbsp;&nbsp;&nbsp;"]:::result
        Duplicate["DUPLICATE<br/>merge provenance&nbsp;&nbsp;&nbsp;&nbsp;"]:::result
        Correction["CORRECTION<br/>supersede old record&nbsp;&nbsp;&nbsp;&nbsp;"]:::rule
        Conflict["CONFLICT<br/>preserve both sides&nbsp;&nbsp;&nbsp;&nbsp;"]:::danger

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

    subgraph Govern["03 · GOVERN&nbsp;&nbsp;&nbsp;&nbsp;"]
        direction LR
        Receipt[("Evidence event<br/>version receipt&nbsp;&nbsp;&nbsp;&nbsp;")]:::store
        Review["CLI or desktop review&nbsp;&nbsp;&nbsp;&nbsp;"]:::surface
        Action["Correct · merge<br/>restore · delete&nbsp;&nbsp;&nbsp;&nbsp;"]:::rule
        Snapshot["Reversible<br/>snapshot&nbsp;&nbsp;&nbsp;&nbsp;"]:::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

Signal	Governance action
Duplicate or stale memory	Inspect the canonical record and supersede chain; restore an earlier version when needed
Conflicting memories	Keep both visible until the conflict is resolved deliberately
Secrets, tokens, or credentials	Quarantine the record so it cannot enter active shared memory
Incorrect automatic organization	Correct, merge, lock, restore, or roll back with evidence
Multiple coding agents	Bind agents to one shared group while preserving source identity and scope
Mandatory rules	Assign rules to an Agent, project, provider, runtime role, or shared group

Rules and history stay separate

MemoryGuard deliberately keeps governed long-term memory and raw conversation history on different paths.

Surface	Purpose	Context behavior
Rules and habits	Preferences, procedures, corrections, facts, projects, and scoped mandatory rules	Mandatory rules use a bounded independent budget; ordinary records are recalled when relevant
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
Neuron graph	Navigation and governance over memory, rules, projects, agents, and sessions	History nodes contain safe metadata and summaries, not raw chat content

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&nbsp;&nbsp;&nbsp;&nbsp;"]
        direction TB
        Archive[("Raw local history&nbsp;&nbsp;&nbsp;&nbsp;")]:::historyStore
        Search["Search summaries&nbsp;&nbsp;&nbsp;&nbsp;"]:::history
        Timeline["Bounded timeline&nbsp;&nbsp;&nbsp;&nbsp;"]:::history
        Read["Explicit turn or session&nbsp;&nbsp;&nbsp;&nbsp;"]:::history
        Preview["Evidence-backed<br/>extraction preview&nbsp;&nbsp;&nbsp;&nbsp;"]:::history
        Confirm["Explicit acceptance&nbsp;&nbsp;&nbsp;&nbsp;"]:::surface
        Isolation["NO AUTOMATIC<br/>BOOTSTRAP PATH&nbsp;&nbsp;&nbsp;&nbsp;"]:::barrier

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

    subgraph GovernedMemory["GOVERNED LONG-TERM MEMORY&nbsp;&nbsp;&nbsp;&nbsp;"]
        direction TB
        Mandatory["Scoped mandatory rules&nbsp;&nbsp;&nbsp;&nbsp;"]:::rule
        Assignments["Agent · project<br/>role · group scope&nbsp;&nbsp;&nbsp;&nbsp;"]:::core
        RulePack["Mandatory-rule<br/>budget&nbsp;&nbsp;&nbsp;&nbsp;"]:::budget
        Ordinary["Facts · preferences<br/>projects · procedures&nbsp;&nbsp;&nbsp;&nbsp;"]:::memory
        Recall["Task-relevant<br/>recall budget&nbsp;&nbsp;&nbsp;&nbsp;"]:::budget
        Context["BOUNDED CONTEXT PACKET&nbsp;&nbsp;&nbsp;&nbsp;"]:::context

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

    HistoryPath ==>|GOVERNED WRITE&nbsp;&nbsp;&nbsp;&nbsp;| 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

Host	Integration	Current boundary
Claude Code	Global MCP binding, redirect rules, user-level lifecycle Hook	Verified takeover path
Codex	Global MCP binding, redirect rules, user-level lifecycle Hook	Verified takeover path
Cursor	Global MCP binding, redirect rules, user-level lifecycle Hook	Verified takeover path
TRAE	MCP binding and redirect rules	No verified Hook seam; reported as a fallback instead of full takeover

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

Layer	Responsibility
Evidence	Authorized files, documents, host-native memory, external MCP descriptors, and conversation archives
Memory	Local SQLite shared-memory stores, scoped rules, provenance, conflicts, quarantine, and versions
Governance	MCP tools, CLI, desktop console, provider adapters, Hooks, confirmation bridges, and rollback

The shared-memory store is the governed source of truth. Evidence remains traceable without being treated as automatically trusted memory.

Privacy and safety

MemoryGuard runs as a local MCP stdio server.
Shared memory and conversation history are stored locally under .memoryguard/.
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:

Command	Purpose
`audit [path]`	Run a read-only audit and generate a report
`open [path]`	Open the latest interactive report
`explain <finding_id>`	Explain evidence and risk for a finding
`plan <finding_ids...>`	Build a minimal fix plan without writing
`apply <plan_id>`	Apply a confirmed plan with backup and rescan
`verify`	Compare the workspace before and after a change
`undo <change_id>`	Restore a backed-up change and verify it
`source <action>`	List, add, remove, or preview authorized sources
`scan`	Scan authorized sources and build the coverage ledger
`import <action> <bundle>`	Preview or create an offline import bundle
`doctor`	Diagnose installation and integration state
`mcp-status`	Inspect local shared-memory groups
`hooks <action>`	Install, inspect, pause, repair, or remove host Hooks
`gc [path]`	Preview or apply garbage collection for rebuildable artifacts
`desktop`	Launch the trusted desktop executor

Run memoryguard --help or memoryguard <command> --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

Roadmap

Current: local MCP memory, automatic organization, scoped rules, conversation evidence, provider adapters, governance UI, and rollback.
Next: stronger automatic lifecycle governance, including decay, derivation, consolidation, and clearer governance reports.
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

Development Status
- 3 - Alpha
Intended Audience
- Developers
Operating System
- OS Independent
Programming Language
- Python :: 3
- Python :: 3 :: Only
Topic
- Software Development :: Libraries

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

agent_memguard-0.5.1.tar.gz (1.3 MB view details)

Uploaded Aug 6, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

agent_memguard-0.5.1-py3-none-any.whl (1.1 MB view details)

Uploaded Aug 6, 2026 Python 3

File details

Details for the file agent_memguard-0.5.1.tar.gz.

File metadata

Download URL: agent_memguard-0.5.1.tar.gz
Upload date: Aug 6, 2026
Size: 1.3 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for agent_memguard-0.5.1.tar.gz
Algorithm	Hash digest
SHA256	`6676ee3679e73c1bbedcbe29130a566d60f042ac0520386401ead00ce34ecc1f`
MD5	`c5afbbdd6cb8a8b06edffdffb0eff632`
BLAKE2b-256	`cd62f509c72b2ae718918f4cd2898b9327ef336f797ba7082427b6091c388002`

See more details on using hashes here.

Provenance

The following attestation bundles were made for agent_memguard-0.5.1.tar.gz:

Publisher: publish.yml on irisxc4/memoryguard

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: agent_memguard-0.5.1.tar.gz
- Subject digest: 6676ee3679e73c1bbedcbe29130a566d60f042ac0520386401ead00ce34ecc1f
- Sigstore transparency entry: 2358158361
- Sigstore integration time: Aug 6, 2026
Source repository:
- Permalink: irisxc4/memoryguard@e8ab69839563dd01a3db71ae8d020def92304250
- Branch / Tag: refs/tags/0.5.1
- Owner: https://github.com/irisxc4
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@e8ab69839563dd01a3db71ae8d020def92304250
- Trigger Event: release