# PruneMem > MCP-compatible memory governance for AI agents — with structure, state, and lifecycle. - **Type:** MCP server - **Install:** `agentstack add mcp-wpoithge-prunemem` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Wpoithge](https://agentstack.voostack.com/s/wpoithge) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Wpoithge](https://github.com/Wpoithge) - **Source:** https://github.com/Wpoithge/PruneMem ## Install ```sh agentstack add mcp-wpoithge-prunemem ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # PruneMem A memory governance system for AI agents — with structure, state, and lifecycle. --- ## The problem Most agents get worse the longer you use them. - They search for the same things over and over - Important decisions get tangled with trivial notes - Old memories pile up and are never cleaned - Active tasks and cold archives blur together - Long-running tasks lose track of where they left off The usual fixes — bigger context windows, smarter retrieval, or manual prompt engineering — don't fix the root cause: **memory without governance**. Information needs organization, expiration, and maintenance just like any other system. ## What PruneMem does PruneMem treats agent memory as an infrastructure layer with three core ideas: - **Structure** — Layered long-term memory (L0–L3) so retrieval knows what to prioritize - **State** — Working memory and runtime context for active session continuity - **Lifecycle** — Automated governance (merge, expire, validate, repair) so the memory layer stays clean over time PruneMem does not replace your vector store or retrieval mechanism — it sits upstream of it. You feed PruneMem session transcripts or facts; it judges what to keep and where to put it, and maintains clean, deduplicated, lifecycle-managed registries. **At query time, you bring your own retrieval**: point a vector store or search index (for example, QMD) at the files PruneMem maintains, and query them however your host already does. In short — PruneMem owns *governance* (what to keep, where, for how long); your retrieval layer owns *recall*. ## What's in this repo This repository contains: - Core memory governance operations (extract, judge, curate, validate, maintain) - Layered registry implementations (L0 ephemeral → L3 canonical) - Working memory and execution context primitives - Session archive builder - MCP server exposing 11 tools for integration with any MCP-compatible host - Host integration assets: a governance skill, an agent playbook, and Claude Code / Codex plugins (lifecycle hooks) It intentionally **does not** include: - Private workspace data or chat logs - Hard-coded vendor integrations (use adapters instead) - Retrieval mechanism (the read path is the host's responsibility) - Production secrets or credentials ## Current release status **Current version: `0.4.0`** Building on the v0.3.0 MCP server, this release adds field-tested host integration for Hermes, Claude Code, and Codex: a governance skill, plugins with lifecycle hooks, and a thin CLI. See [CHANGELOG.md](CHANGELOG.md) for version history. ## Architecture overview ```mermaid flowchart LR A[Session packet] --> B[Extract facts] B --> C[Judge & classify] C --> D[Update registries] D --> E[Layered storageL0 / L1 / L2 / L3] E --> F[Working memory] F --> G[Runtime context] G --> H["Agent turn(host responsibility)"] E --> I[Curator applymerge / expire / validate] I --> E ``` **Data flow:** A session packet goes through extract → judge → registry update. Registries feed layered storage, working memory, and runtime context. A background curator process maintains registry health over time. ## Quick start PruneMem is an MCP server (stdio transport). Clone it, install dependencies, and register it with your host: ```bash git clone https://github.com/Wpoithge/PruneMem.git cd PruneMem npm install ``` Register with your host (use an absolute path to `bin.js`): - **Claude Code** — `claude mcp add --scope user prunemem node /absolute/path/to/PruneMem/src/mcp/bin.js` - **Codex CLI** — `codex mcp add prunemem -- node /absolute/path/to/PruneMem/src/mcp/bin.js` - **Hermes Agent** — `hermes mcp add prunemem --command node --args /absolute/path/to/PruneMem/src/mcp/bin.js` You should see **11 tools** discovered. For proactive memory governance — guidance on when and how the agent should call these tools — install the governance skill, and on Claude Code / Codex the plugin that also bundles lifecycle hooks (session-start context injection, pre-compact snapshot). See the host-specific guide below. ## Integration guides Host-specific setup guides: - [MCP capability surface](docs/integrations/mcp-surface.zh.md) (Chinese-only quick reference) - [Hermes Agent](docs/integrations/hermes.md) - [Claude Code](docs/integrations/claude-code.md) - [Codex CLI](docs/integrations/codex-cli.md) Each guide includes a troubleshooting section. ## For AI agents If you are an AI agent helping a user integrate PruneMem with their host, this section is for you. PruneMem is an **MCP server** with **stdio transport** — that is how hosts integrate it. It also ships a thin `prunemem` CLI (list and invoke tools directly, for testing/scripting), but the CLI is not the integration path. It is not a Python package and is not yet published to npm. ### Prerequisites - Node.js (any recent LTS version) - `npm` available in PATH - Git available ### Installation steps ```bash git clone https://github.com/Wpoithge/PruneMem.git cd PruneMem npm install ``` ### Host-specific registration commands | Host | Registration command | |---|---| | Hermes Agent | `hermes mcp add prunemem --command node --args /absolute/path/to/PruneMem/src/mcp/bin.js` | | Claude Code | `claude mcp add --scope user prunemem node /absolute/path/to/PruneMem/src/mcp/bin.js` | | Codex CLI | `codex mcp add prunemem -- node /absolute/path/to/PruneMem/src/mcp/bin.js` | For Hermes, after registration, verify with: ```bash hermes mcp test prunemem ``` Expected output: `✓ Connected` and `Tools discovered: 11`. ### After integration PruneMem provides 11 MCP tools (5 read-class + 4 single-write + 2 composite). All write-class tools default to `write: false` (dry-run). See [docs/mcp-tools.md](docs/mcp-tools.md) for the complete tool catalog. **Proactive usage**: Beyond the raw 11 tools, PruneMem ships a governance skill (`skills/prunemem-memory-governance/SKILL.md`) and an [agent playbook](docs/agent-playbook.md) that guide when and how an agent should call the tools. On Claude Code and Codex, a plugin bundles this skill plus lifecycle hooks (session-start context injection, pre-compact snapshot). See the host integration guides for setup. ## MCP capabilities PruneMem exposes its memory governance operations as an [MCP](https://modelcontextprotocol.io) server with **11 tools** (stdio transport). This means PruneMem can be plugged into any MCP-compatible host: - [Hermes Agent](https://hermes-agent.nousresearch.com) - [Claude Code](https://docs.claude.com/en/docs/claude-code) - [Codex CLI](https://developers.openai.com/codex) - Any other MCP host See [docs/mcp-tools.md](docs/mcp-tools.md) for the complete tool reference, and [docs/mcp-server.md](docs/mcp-server.md) for protocol details. ## Safety defaults PruneMem ships with two layers of write protection enabled by default: 1. **Dry-run by default** — All write-capable MCP tools default to `write: false`. To actually persist changes, the caller must explicitly pass `write: true`. 2. **Isolated preset** — Pass `preset: "isolated"` to redirect all writes to a sandboxed `.prunemem-isolated/` directory, leaving the real workspace untouched. Additionally, the judgment pipeline targets the `L1` layer by default — the shallowest, most ephemeral memory layer — until the caller explicitly upgrades to deeper layers. ## Data ownership PruneMem stores memory using its own schema (working-state, execution-plan, registries, lifecycle, topics, dedupe). This schema is documented in [docs/](docs/) but is **not** a standard adopted by other memory systems. This means: - **You can leave anytime**. Uninstall PruneMem via `hermes mcp remove prunemem` (or equivalent) and your host works as before. Your memory data files stay on disk (under your workspace) for you to inspect, archive, or delete. - **However, data does not transfer to other memory tools automatically**. If you accumulate memory in PruneMem and later want to switch to agentmemory, memos, letta, mem0, etc., manual data migration is required. PruneMem currently does not provide automated export/import tools. We acknowledge this is a real limitation. Import/export tooling for cross-system migration is on the [Roadmap](#roadmap) (planned, no specific version). Until then: if you anticipate needing migration, keep your own backups of the workspace directory. ## Repository layout ``` src/ ├── core/ # Main operations: extract, judge, update, curate, validate, maintain ├── lib/ # Utilities: paths, schema, registry, similarity, validate-input ├── runtime/ # Execution context, archive builder, provider factory ├── working/ # Working memory primitives ├── extract/ # Fact extraction ├── judge/ # LLM classification and scoring ├── archive/ # Session packet builder ├── mcp/ # MCP server and tool handlers └── adapters/ # Model provider and storage backend adapters docs/ ├── integrations/ # Host-specific setup guides (Hermes, Claude Code, Codex) ├── mcp-server.md # MCP server integration guide ├── mcp-tools.md # Complete tool reference ├── governance.md # Registry governance chain ├── layers-and-lifecycle.md # Layered storage details └── ... # Additional concept and design docs examples/ # Demo workspace with sample data scripts/ # Validation and demo scripts tests/ # Regression and MCP tests skills/ # Governance skill (host-loadable) plugins/ # Claude Code / Codex plugins (skill + lifecycle hooks) ``` ## Key docs - [docs/governance.md](docs/governance.md) — How the governance chain works (update-registries → curator-apply → validate → repair) - [docs/layers-and-lifecycle.md](docs/layers-and-lifecycle.md) — L0–L3 storage, working memory, runtime context, session archives - [docs/execution-context.md](docs/execution-context.md) — Milestone system for long-running tasks - [docs/mcp-server.md](docs/mcp-server.md) — How to start and connect the MCP server - [docs/mcp-tools.md](docs/mcp-tools.md) — Complete schema and examples for all 11 tools - [docs/faq.md](docs/faq.md) — Frequently asked questions ## Roadmap - npm publish for one-line installation - Memory data import/export tooling for cross-system migration (planned, no specific version) - More multi-host example workflows - v1.0.0 stable release after broader real-world validation ## License MIT. See [LICENSE](LICENSE). ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Wpoithge](https://github.com/Wpoithge) - **Source:** [Wpoithge/PruneMem](https://github.com/Wpoithge/PruneMem) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-wpoithge-prunemem - Seller: https://agentstack.voostack.com/s/wpoithge - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.