memoryguard

<h1 align="center">MemoryGuard</h1>

<!-- mcp-name: io.github.MerakOsiris/memoryguard -->

<p align="center">
  <strong>Governed shared memory for coding agents.</strong><br />
  Local-first MCP memory with automatic organization, scoped rules, evidence, and rollback.
</p>

<p align="center">
  <a href="https://pypi.org/project/agent-memguard/"><img src="https://img.shields.io/pypi/v/agent-memguard.svg?label=PyPI" alt="PyPI version" /></a>
  <a href="https://github.com/irisxc4/memoryguard/actions/workflows/ci.yml"><img src="https://github.com/irisxc4/memoryguard/actions/workflows/ci.yml/badge.svg" alt="CI status" /></a>
  <a href="https://github.com/irisxc4/memoryguard/blob/main/pyproject.toml"><img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python 3.10 or newer" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-2ea44f" alt="MIT license" /></a>
  <a href="README.zh-CN.md">中文文档</a>
</p>

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

<p align="center">
  <a href="#quick-start">Quick start</a> ·
  <a href="#upgrade">Upgrade</a> ·
  <a href="#knowledge-library">Knowledge Library</a> ·
  <a href="#system-architecture">Architecture</a> ·
  <a href="#supported-hosts">Supported hosts</a> ·
  <a href="#privacy-and-safety">Privacy and safety</a>
</p>

<p align="center">
  <img src="docs/assets/neuron-graph-live.gif" alt="Animated MemoryGuard neuron graph with governed memory categories and signals moving through the local projection" width="1120" />
</p>

<p align="center">
  <sub>A synthetic governed projection: signals move through memory categories while raw conversation text remains outside the graph.</sub>
</p>

## What's New in v0.7.15

- **Automatic CodeGraph builds:** Trusted bootstrap starts a project's first
  build in a background process. Default and per-project switches persist;
  disabling automation preserves the graph. Supported file-write events
  trigger incremental refresh.
- **Clear graph navigation:** Switch between a file overview and symbols,
  filter by file, inspect neighboring relations, and use zoom controls.
- **Bounded temporary storage:** Ordinary graph queries read SQLite directly
  instead of retaining full-database copies. Validation and installation
  temporary files use the owning project/deployment cache and are cleaned up
  when the operation ends.

See the [v0.7.15 release note](docs/releases/v0.7.15.md) and
[CodeGraph automation details](docs/codegraph-automation.md). Reconnect or
restart hosts after upgrading and repairing their provider integration.

### Earlier governance improvements

v0.7.13 strengthens mandatory-rule replacement and recovery, improves
audience-aware identity handling, and improves conflict resolution:

- **Safe mandatory-rule replacement:** Replacements validate the final
  mandatory package against audience matching, canonical rules, deduplication,
  sensitivity checks, and publication budgets. Equivalent unlocked predecessors
  retire in the same transaction; failed validation rolls back the complete
  update. See the [replacement and recovery details](docs/mandatory-rule-replacement.md).
- **Native Agent/group audience matching:** Matching and deduplication no longer
  split the same native audience solely by provider or runtime role. Distinct
  Agent identities remain separate, and project-scoped audiences retain their
  project boundaries. Provider repair uses the verified identity for its target
  provider.
- **Readable, atomic conflict resolution:** Conflict views preserve readable
  peer information, and resolution keeps peer groups intact while applying the
  selected changes atomically. Ambiguous conflicts remain unresolved.
- **Cursor Hook protection:** Cursor MemoryGuard Hooks now use a 30-second
  timeout, up from 15 seconds, with `failClosed: true`.

v0.7.14 only corrects release metadata for the GitHub repository rename; it does not change runtime behavior. See the [v0.7.14 release note](docs/releases/v0.7.14.md).

See the [v0.7.13 release note](docs/releases/v0.7.13.md) and
[release history](CHANGELOG.md).

Earlier release details are kept in the [Changelog](CHANGELOG.md) and
[GitHub release records](https://github.com/irisxc4/memoryguard/releases).

### Token evidence and demo

Usage events distinguish `measured_cached_input` from
`measured_cache_write_input`. `measured_cache_coverage.cache_read` and
`cache_write` report `complete`, `partial`, or `unavailable`; measured zero
remains `0`, while missing provider data remains `None`/`unavailable`.
Character-based estimates remain explicitly labelled
`estimated mg_deterministic_unit`, never provider tokens.

Run the benchmark only against an authorized local workspace:

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

Read [the benchmark guide](docs/benchmarks/README.md) 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.

| 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

```mermaid
%%{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[("V2 DOMAIN STORES<br/>Memory · Rules · Evidence · Content&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,stro