MemoryCustodian

Overview

MemoryCustodian is an open-source memory system for coding agents. It gives Codex, Claude Code, Gemini-style agents, and other coding assistants durable project memory without relying on a hosted service, vector database, or ever-growing prompt file.

The core idea is simple: project memory lives as plain Markdown inside the repository. Decisions, constraints, rejected approaches, current context, and optional area-specific notes can be reviewed, versioned, shared, edited, and deleted like code. A manifest tells the agent which memory files are relevant for a given task, so the agent loads a small context pack instead of everything at once.

For teams using AI code generators, MemoryCustodian addresses a common operational problem: every new agent session starts by relearning the same project decisions. The tool makes that memory explicit, portable, and inspectable.

Key Features

• Repo-native Markdown memory - Memory lives under docs/memory/ as normal Markdown files, making it easy to review in pull requests and commit history.
• Manifest-based context routing - Agents read the manifest and load only the task-relevant files, reducing prompt bloat.
• Cross-agent support - MemoryCustodian includes setup paths for Codex, Claude Code, Gemini-style agents, and direct shell usage.
• Local CLI checks - The CLI can initialize, inspect, validate, compact, migrate, and repair memory structures using deterministic checks.
• Preview-first destructive operations - Forgetting, compaction, and migration require preview flows before applying changes.
• Offline-first design - Routine operations use local files and Python standard-library tooling rather than hosted retrieval infrastructure.

How to Get Started

MemoryCustodian supports several installation paths. The simplest workflow is:

1. Install the MemoryCustodian skill or plugin for your agent environment.
2. Run memory-custodian init --project-root /path/to/project --agent all.
3. Curate the generated brief.md from authoritative project files.
4. Let agents read docs/memory/manifest.md, then only the task-relevant memory files.
5. Add durable decisions, constraints, or rejected approaches when they should survive the current chat.

The project intentionally separates durable memory from chat history. It is not designed to archive every conversation. It is designed to preserve decisions and constraints that future agent sessions need to respect.

Community & Ecosystem

MemoryCustodian is MIT licensed and hosted on GitHub. The repository includes a CLI, reusable agent skill, Codex and Claude plugin metadata, adapters, examples, tests, templates, and evaluation artifacts.

Because the system is file-based, it fits normal software development workflows. Teams can review memory changes like documentation changes, attach them to feature branches, and remove outdated memory through explicit forget or compaction flows.

Pricing & Plans

MemoryCustodian is free and open source.

There is no hosted subscription or paid plan listed in the repository. Users may still need access to their chosen coding agent, such as Codex, Claude Code, or Gemini, but MemoryCustodian itself is free.

Best For

• Developers who frequently restart Codex, Claude Code, Gemini, or similar AI agent sessions
• Teams that want project memory stored in Git rather than a hosted knowledge base
• Open-source maintainers who need portable context for contributors and agents
• Engineering teams that care about explicit decisions, rejected approaches, and constraints
• Users comparing lightweight memory systems with broader AI productivity platforms

FAQ