agent-memguard 0.1.0__tar.gz

agent_memguard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MemoryGuard Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_memguard-0.1.0/PKG-INFO

@@ -0,0 +1,313 @@
+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: gui
+Requires-Dist: pywebview>=5.0; extra == "gui"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+
+# 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).

agent_memguard-0.1.0/README.md

@@ -0,0 +1,286 @@
+# 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).

agent_memguard-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "agent-memguard"
+version = "0.1.0"
+description = "Local-first MCP memory backend and governance console for coding agents"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "MemoryGuard Contributors" }]
+keywords = ["agent", "governance", "memory", "mcp", "skill", "local-first", "claude", "cursor", "codex"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Libraries",
+]
+# 首期零运行时第三方依赖：纯标准库实现，保证无网络、无供应链风险。
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/irisxc4/memoryguard"
+Repository = "https://github.com/irisxc4/memoryguard"
+Documentation = "https://github.com/irisxc4/memoryguard#readme"
+Issues = "https://github.com/irisxc4/memoryguard/issues"
+
+[project.scripts]
+memoryguard = "memoryguard.cli:main"
+
+[project.optional-dependencies]
+# 原生桌面窗口 GUI（可选）。未安装时 `open` 自动降级到 localhost/HTML。
+# 引入理由: 用户需求要求原生窗口；保持可选以维持 Core 零依赖原则（spec §1.3/§10）。
+gui = ["pywebview>=5.0"]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-ra --strict-markers"

agent_memguard-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agent_memguard-0.1.0/setup.py

@@ -0,0 +1,3 @@
+from setuptools import setup
+
+setup()