memoryguard

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

<!-- mcp-name: io.github.irisxc4/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.12

v0.7.12 improves MCP discovery, bounded read delivery, and local usage
telemetry while preserving the existing governed action checks and MCP name:

- **Compact discovery with a complete catalog:** New MCP clients receive 11
  day-to-day tools from `tools/list`, including capability discovery and the
  governed invocation broker. `memoryguard_capabilities` provides paginated
  metadata for registered MCP operations and reviewed headless GUI operations;
  exact advanced MCP names remain callable for compatibility.
- **Bounded read delivery:** Replayable successful reads are capped at 24,000
  UTF-8 bytes across the complete MCP envelope. Eligible oversized reads return
  a short-lived process-local reference rather than truncating data; reads that
  cannot be safely replayed or exceed the snapshot limit return a bounded
  narrowing hint. Pages support UTF-8 offsets and field selection. Private
  references revalidate the original read under the current trusted session and
  binding before each page. Writes and context bootstrap keep their complete
  receipt/mandatory-rule contracts and cannot request response paging.
- **Cache-aware local telemetry:** Provider-reported cache-read and cache-write
  input counts are kept separately with complete/partial/unavailable coverage.
  A measured zero remains zero; missing provider data remains unknown. The
  deterministic unit estimate is labeled as an estimate and does not claim a
  measured token reduction.
- **Governed invocation:** Mutating broker targets still require confirmation
  and a non-empty idempotency key, which are forwarded to the target's existing
  permission, scope, and readiness checks. The MCP name remains
  `io.github.irisxc4/memoryguard`.

See the [v0.7.12 release note](docs/releases/v0.7.12.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,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