MemoryCustodian
Zekun Wang (waittim) · Coding
MemoryCustodian is a free, open-source tool that gives coding agents durable project memory. It stores decisions, constraints, and rejected ideas as plain Markdown files inside your repo, then routes only the task-relevant pieces to the agent through a manifest. The result: less prompt stuffing and more consistent work across sessions, agents, and teammates. It's built for AI coding agent context management, not chat logs.
About MemoryCustodian
What Is MemoryCustodian
MemoryCustodian is an AI coding agent memory tool built for people who work with Codex, Claude Code, Gemini, or any shell-based agent. It also fits teams that share a single repository across multiple agent hosts and want one source of truth. The problem it targets is specific: every new agent session tends to relearn decisions your repository already made. Architecture constraints, preferred workflows, rejected approaches, and the current project shape all get pasted back into prompts, which makes each task heavier than the last. So why does that happen? Because the memory lives in chat, and chat gets wiped.
The fix is to move durable project context into the repository itself. MemoryCustodian keeps that context in plain Markdown under docs/memory/, so humans can review and diff it like code. Before a task, the agent reads a small, bounded context pack instead of the whole history. That's agent context routing in practice. It keeps token usage down and stops the agent from inventing rules you never agreed to.
It's not chat history. It's project memory. That distinction matters, because it means the memory survives a cleared conversation, a switched model, or a new teammate joining the repo. The main trade-off is that you have to write the initial files by hand. A rough brief gets flagged by the built-in status and check commands.
Getting Started
- Ask your coding agent to install the MemoryCustodian skill from its GitHub repo, then initialize it.
- Or run the CLI directly:
memory-custodian init --project-root /path/to/project --agent all(swapallforcodex,claude, orgeminito target one host). - Review the generated files in
docs/memory/, especiallybrief.md, and fill the TODOs from your authoritative project docs. - Record durable memory as you work with
memory-custodian add, tagging each entry with a subject and evidence. - Run
memory-custodian statusandmemory-custodian checkto confirm the protocol is healthy before you rely on it.
Product Information
A quick look at MemoryCustodian's pricing, supported platforms, and performance.
Best for
The users, tasks, and scenarios where this tool fits best.
Users
- Developers using coding agents daily
- Small dev teams sharing a repo
- Anyone switching between Codex, Claude Code, and Gemini
Tasks
- Preserving architecture decisions
- Tracking rejected approaches
- Onboarding a fresh agent session
Scenarios
- Picking up a repo after a long gap
- Reviewing a pull request
- Running agents in CI
Key features
Repo-Native Markdown Memory
MemoryCustodian stores all project memory as plain Markdown in docs/memory/. That means it's reviewable, diffable, committable, and rollback-safe just like your source code, which is exactly the point when the memory encodes real engineering decisions. Nothing is locked in a proprietary database, and teammates can review memory changes in the same pull requests as code.
Manifest-Based Context Routing
Instead of stuffing the full history into every prompt, the tool reads manifest.md first, then brief.md, then only the files the manifest names for your task. Routing uses explicit task and scope inputs, with no semantic guessing or LLM ranking. The agent context routing stays deterministic and predictable. You get a bounded context pack that matches the job at hand.
Canonical Task Types
The CLI ships with a fixed set of task categories: general, planning, implementation, artifact, preferences, history, and maintenance. Calling read --task implementation pulls the memory relevant to writing code, while other tasks load a different slice based on the scope you pass in. A --strict-routing flag fails closed on incomplete or ambiguous scope rather than guessing.
Conservative Memory Writes
Active memory is evidence-backed. Entries get stable IDs like MC-DEC-... and MC-SUBJ-..., and each write needs user confirmation or a project source before it counts as real. Unconfirmed agent observations stay as candidates in inbox.md until a human vouches for them, which keeps phantom rules out of your working memory and away from your code.
Forgetting, Checks, and Maintenance
Forgetting is preview-first and scoped: memory-custodian forget prints a Plan ID you must confirm before anything is deleted. That preview step matters because memory files are shared, so a bad delete can affect everyone's agent at once. Maintenance commands like compact keep files within budget and archive the oldest entries on request. Separate checks cover routing, freshness, privacy, security, and conflicts, including Git merge-aware review against a base branch.
Zero-Dependency Python CLI
The whole tool runs on the Python standard library. No third-party runtime dependencies at all. It works offline and needs no RAG pipeline or vector database, which avoids embedding latency and hallucinated retrieval. Installation is one editable pip install or a bundled script wrapper.
Pros and cons
Pros
- Free and open source under the MIT License, with no paid tier or usage caps.
- Works offline with zero third-party runtime dependencies and no vector database.
- Memory lives in your repo as diffable Markdown, so it's reviewable and rollback-safe.
- One memory set supports Codex, Claude Code, Gemini, and generic shell agents.
- Evidence-backed writes and stable IDs cut phantom rules and accidental overwrites.
- Light on resources: no server, no database, just Markdown files in your repo.
Cons
- It's a developer tool aimed at coding agents, so non-technical users will find the CLI and protocol concepts heavy.
- Getting value depends on curating the initial `brief.md`; an uncurated setup gets flagged and routing quality suffers.
- Memory recall is deterministic and rule-based, so it won't auto-summarize messy conversations for you.
Frequently asked questions
It gives AI coding agents durable project memory. It stores decisions, constraints, and rejected approaches in your repo and loads only the task-relevant parts. So agents stop relearning the same context every session.
Related content
Explore related tools, skills, and articles for MemoryCustodian.
MemoryCustodian Alternatives
Forefront
Forefront · CodingForefront is a web platform for building with open-source AI. It lets you fine-tune leading open-source language models on your own data, evaluate how they perform, and run them through an API or export them to host yourself. Developers who want the convenience of a closed-source platform but insist on owning their models and data are the target audience here.
Startkit
StartKit.AI · CodingStartkit is a boilerplate for building AI SaaS and AI wrapper products. Think of it as an AI startup boilerplate with the boring parts already wired up: authentication, Stripe and Lemon Squeezy payments, usage limits, transactional email, and an AI API starter that talks to OpenAI, Anthropic, Groq, or Llama. You clone the repo, set your price, and start on the part of your product that people actually pay for. It's Next.js under React and Tailwind, so most of the boilerplate code already feels familiar.
Testim
Tricentis · CodingTestim is an AI-powered test automation platform for building and running end-to-end tests across web, mobile, and Salesforce applications. It leans on machine learning to keep tests stable when an interface changes, so teams spend less time fixing broken selectors. Not bad for an automated testing tool you can start using today. You create tests by recording actions in a browser, then optionally add JavaScript when you need more control. It's a solid pick for busy QA teams.