PruneMem

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

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:

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

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:

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 server with 11 tools (stdio transport).

This means PruneMem can be plugged into any MCP-compatible host:

• Hermes Agent
• Claude Code
• Codex CLI
• 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
• Source: Wpoithge/PruneMem
• License: MIT

Install and usage instructions live in the source repository linked above.