Metadata-Version: 2.1
Name: agent-memguard
Version: 0.1.0
Summary: Local-first MCP memory backend and governance console for coding agents
Author: MemoryGuard Contributors
License: MIT
Project-URL: Homepage, https://github.com/irisxc4/memoryguard
Project-URL: Repository, https://github.com/irisxc4/memoryguard
Project-URL: Documentation, https://github.com/irisxc4/memoryguard#readme
Project-URL: Issues, https://github.com/irisxc4/memoryguard/issues
Keywords: agent,governance,memory,mcp,skill,local-first,claude,cursor,codex
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Provides-Extra: gui
Requires-Dist: pywebview>=5.0; extra == "gui"

# MemoryGuard

> Local-first MCP memory backend and governance console for coding agents.
>
> 本地优先的 MCP 记忆后端与治理台，面向编程 Agent。([中文文档](README.zh-CN.md))

MemoryGuard lets multiple coding agents write to one shared memory layer, then
automatically organizes, quarantines, supersedes, and rolls back memories —
without turning the GUI into an approval queue.

## What It Does

MemoryGuard provides a local MCP stdio memory backend that coding agents
(Claude Code, Codex, Cursor, and others) can write to using the same memory
mechanisms they already use. Every write is auto-organized — classified,
deduplicated, superseded, quarantined, or compressed — so the shared memory
stays clean. A governance console lets you observe, edit, merge, roll back,
and resolve conflicts after the fact, not by approving every write.

（中文：MemoryGuard 提供本地 MCP 记忆后端，Agent 按原有方式写入，系统自动整理，
GUI 事后治理——无需手动批准每次写入。）

## Features

- **MCP memory backend** — 6 core tools: read / search / write / update / delete / status
- **Auto-organize** — classify / dedup / supersede / conflict / quarantine / derive / compress
- **Multi-agent shared memory groups** — multiple agents write to one governed memory
- **GUI governance console** — observe, edit, merge, lock, restore, roll back (not an approval queue)
- **Provider adapters** — one-command setup for Claude Code / Codex / Cursor
- **Rollback and version history** — all governance actions are versioned and reversible
- **No account, no server, no telemetry** — everything stays local

## Quick Start

### Install

**One-line install (recommended):**

```bash
pip install agent-memoryguard
```

With GUI support (optional, for desktop window):

```bash
pip install "agent-memoryguard[gui]"
```

**Or from source:**

```bash
git clone https://github.com/irisxc4/memoryguard.git
cd memoryguard
pip install -e .
```

Verify the installation:

```bash
memoryguard doctor
```

### Configure your Agent

**One-line setup (auto-writes MCP config + instruction file):**

```bash
# Claude Code
memoryguard source add . && python -m memoryguard.provider_adapters install claude

# Codex
memoryguard source add . && python -m memoryguard.provider_adapters install codex

# Cursor
memoryguard source add . && python -m memoryguard.provider_adapters install cursor
```

Or use the MCP tool directly from your agent:

```
memoryguard_provider_install(provider="claude")
```

**Manual config** - see the install guides for details:

- [Claude Code](docs/install-claude-code.md)
- [Codex](docs/install-codex.md)
- [Cursor](docs/install-cursor.md)

<details>
<summary>Manual MCP config (all agents use the same server)</summary>

**Claude Code** — `.mcp.json` (project root):

```json
{
  "mcpServers": {
    "memoryguard": {
      "command": "python",
      "args": ["-m", "memoryguard.mcp_server"]
    }
  }
}
```

**Codex** — `~/.codex/config.toml`:

```toml
[mcp_servers.memoryguard]
command = "python"
args = ["-m", "memoryguard.mcp_server"]
```

**Cursor** — `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "memoryguard": {
      "command": "python",
      "args": ["-m", "memoryguard.mcp_server"]
    }
  }
}
```

</details>

### Use

```bash
memoryguard doctor            # diagnose installation and environment
memoryguard mcp-status        # query MCP memory backend status
python -m memoryguard.mcp_server  # start the MCP stdio server (run by your agent)
memoryguard audit .           # read-only workspace scan, generate report
memoryguard open .            # open the latest report
```

Once your agent is configured, it writes memories through the
`memoryguard_memory_write` MCP tool. MemoryGuard auto-organizes every write.
Open the GUI to observe and govern the results.

## How It Works

MemoryGuard has three layers:

| Layer | Role |
|---|---|
| **Data layer** | Agent native memory, files, external MCP, documents — provides raw evidence, no governance |
| **Memory layer** | MemoryGuard MCP shared memory backend — the single shared source of truth; agents write here; auto-organize runs on every write |
| **Governance layer** | GUI + CLI — observe, edit, merge, lock, restore, roll back after the fact |

```
Agent writes memory
  → memoryguard_memory_write (MCP tool)
  → raw event
  → auto-organize (classify / dedup / supersede / conflict / quarantine / derive / compress)
  → active shared memory
  → GUI governance (observe / correct / override / roll back)
```

## Commands

| Command | Description |
|---|---|
| `audit [path]` | Read-only scan, generate report |
| `open [path]` | Open latest report in a window |
| `explain <finding_id>` | Explain a finding's evidence and risk |
| `plan <finding_ids...>` | Generate minimal fix plan (no write) |
| `apply <plan_id>` | Apply a plan: backup + patch + rescan |
| `verify` | Rescan and compare before/after |
| `undo <change_id>` | Restore from backup and re-verify |
| `source <action>` | Manage authorized sources (list / add / remove / preview) |
| `scan` | Read-only scan, build coverage ledger |
| `import <action> <bundle>` | Offline import bundle (preview / create) |
| `memory <action>` | Memory build & release (build-plan / build-apply / verify / rollback) |
| `doctor` | Diagnose installation and environment |
| `mcp-status` | Query MCP memory backend status |

## MCP Tools

### Memory Backend (6 core tools)

| Tool | Description |
|---|---|
| `memoryguard_memory_read` | Read a single memory record by ID |
| `memoryguard_memory_search` | Search memories by query, kind, or status |
| `memoryguard_memory_write` | Write a new memory; auto-organizes on write |
| `memoryguard_memory_update` | Update a memory (body / kind / status) |
| `memoryguard_memory_delete` | Soft-delete a memory |
| `memoryguard_memory_status` | Get shared memory group status |

### Audit & Scan

| Tool | Description |
|---|---|
| `memoryguard_audit` | Read-only workspace scan |
| `memoryguard_explain` | Explain a finding's evidence and risk |
| `memoryguard_list_sources` | List authorized sources |
| `memoryguard_scan_summary` | Scan + coverage ledger |
| `memoryguard_neuron_graph` | Read neuron graph projection |
| `memoryguard_import_preview` | Preview an import bundle |
| `memoryguard_build_plan` | Generate a memory build plan (no write) |

### Agent Binding

| Tool | Description |
|---|---|
| `memoryguard_binding_create` | Bind an agent to a share group |
| `memoryguard_binding_list` | List agent bindings |

### External MCP

| Tool | Description |
|---|---|
| `memoryguard_external_mcp_list` | List imported external MCP descriptors |
| `memoryguard_external_mcp_import` | Import an external MCP descriptor (L0–L4 classification) |

### Document & Discovery

| Tool | Description |
|---|---|
| `memoryguard_extract_memories` | Extract memory segments from a source file (read-only preview) |
| `memoryguard_accept_candidates` | Accept extracted candidates and write to shared memory |

### Semantic & Provider

| Tool | Description |
|---|---|
| `memoryguard_semantic_check` | Check text for semantic duplicates / conflicts |
| `memoryguard_provider_install` | Install provider adapter (Claude / Codex / Cursor) |

## Governance GUI

The GUI is a **governance console, not an approval queue**. Agents write
memories through MCP; MemoryGuard auto-organizes them. The GUI then shows you:

- Recent raw writes from agents
- Auto-organize results (classify / dedup / compress)
- Supersede chains (what was covered and why)
- Conflict queue (memories that need human arbitration)
- Quarantine queue (secrets / tokens / credentials isolated automatically)
- Derived memories (procedures / preferences from repeated behavior)

Governance actions: **edit, merge, split, lock, restore, delete, roll back**.
Every action is versioned and reversible.

## FAQ

**Does MemoryGuard require a server or account?**
No. It runs as a local MCP stdio server. No account, no cloud, no telemetry.

**Does it fully replace my agent's native memory?**
MemoryGuard redirects writes to the MCP backend where the agent supports it.
Some agents cannot fully disable native memory — MemoryGuard uses a
redirected / observed / unsupported classification instead of pretending
everything can be turned off.

**Does the GUI approve every write?**
No. The MCP backend accepts writes and auto-organizes them. The GUI only
governs the results afterward.

**Is my memory uploaded anywhere?**
No. All data stays in a local SQLite database under `.memoryguard/`.

**Can I roll back changes?**
Yes. All governance actions are versioned. You can restore, un-supersede, and
roll back to any previous version.

## Roadmap

- **Now (open-source core):** local MCP memory backend + auto-organize + GUI governance + provider adapters + rollback. This repository.
- **Later:** enhanced governance features (decay, derivation, governance reports). No timeline committed.
- **Later:** team and enterprise features. No timeline committed.

We do not promise dates for future features. The open-source core is designed
to be fully usable on its own.

## License

MIT — see [LICENSE](LICENSE).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). By submitting a PR you agree to the
[CLA](CLA.md).
