Coding agents have a memory problem. Every new session starts from scratch: the agent can read the repository’s code, but it cannot read the repository’s reasoning. A developer explains why SQLite was rejected. A week later, a different session proposes SQLite again. The cycle repeats.
MemoryCustodian, an open-source tool published on GitHub by developer Zekun Wang, proposes a solution that is both old-fashioned and radical: store durable project memory as plain Markdown files inside the repository, and load only the files relevant to the current task. No vector database. No proprietary memory store. No chat-history dump. Just a docs/memory/ directory with a manifest that tells the agent what to read.
The tool is not a product. It is a provocation. And it arrives at exactly the right moment.
The problem MemoryCustodian addresses is structural. The major coding-agent platforms — OpenAI’s Codex, Anthropic’s Claude Code, Google’s Gemini CLI — all ship with platform-specific instruction files: CLAUDE.md, GEMINI.md, AGENTS.md. Developers fill these files with project constraints, rejected approaches, and architectural decisions. Over time, those files grow into unstructured context dumps. Every task pays the cost of loading the entire history, even when only a subsystem decision matters.
MemoryCustodian’s core insight is that memory and context are separate concerns. The repository can accumulate knowledge over time, but each task should load only what it needs. The mechanism is a manifest file that routes context by task type: a planning task loads brief.md, decisions.md, constraints.md, and do-not-use.md. A documentation task loads brief.md and writing preferences but not infrastructure history. A subsystem-specific task loads only the relevant area file.
The tool ships with a demo called NightNotes, an intentionally incomplete command-line application. The demo’s acceptance test documents a missing persistence behavior. The repository already contains durable decisions: persistent state should use human-readable local JSON, routine operation must work without network access, the application should use only the Python standard library, SQLite is rejected. A new agent session, prompted to plan the implementation, must recover those facts from the project memory. The prompt does not mention JSON, SQLite, or offline operation. The agent must route itself.
That is the bet. Agents are smart enough to navigate a structured memory directory if the structure exists. The question is whether teams will adopt the discipline to maintain it.
MemoryCustodian’s design is intentionally conservative. The CLI validates structure and enforces boundaries, but it does not infer meaning. The agent or user decides whether a statement is a decision, a constraint, or a rejected approach. The CLI checks budgets, previews mutations, and applies bounded operations safely. This is a governance layer, not an intelligence layer. The tool was built with Codex and GPT-5.6 during OpenAI Build Week, but those models are not runtime dependencies. The memory files are plain Markdown. Any agent that can read a repository can use them.
The tool is not a replacement for source documentation or a general-purpose search engine. It is not designed to archive everything an agent has ever seen. Temporary thoughts, unfinished ideas, and one-off debugging observations should not become permanent project memory. The goal is not maximum memory. The goal is useful continuity with controlled context cost.
That restraint is the tool’s strongest argument. The current trajectory of agent memory is toward larger context windows and more sophisticated retrieval. Anthropic’s Claude ships with a 200,000-token context window. OpenAI’s GPT-5.6 can process millions of tokens. The assumption is that more context is always better. MemoryCustodian challenges that assumption by arguing that context is a routing problem, not a capacity problem.
The tool has clear limitations. It requires manual curation. The initializer creates a scaffold, not an understanding of the repository. Teams must review the generated files and curate brief.md, decisions, constraints, and rejected approaches from authoritative project information. The tool does not automatically surface what should be remembered. It provides the structure for what a human or agent decides to record.
MemoryCustodian also assumes a single repository as the unit of memory. Multi-repository projects, monorepos with many teams, and projects that span multiple agent platforms will need to adapt the protocol. The tool’s cross-agent compatibility is a strength — the same Markdown files work with Codex, Claude Code, and Gemini CLI — but the routing logic lives in the manifest, which must be maintained.
The broader question is whether the industry will converge on a standard for agent memory. MemoryCustodian is one proposal. It is open-source, repo-native, and agent-agnostic. It does not require a platform subscription, a cloud service, or a proprietary format. It is a set of conventions enforced by a CLI. That makes it a candidate for the kind of low-friction standard that the ecosystem needs.
The tool’s existence also highlights a gap in the major platforms. Codex, Claude Code, and Gemini CLI all provide platform-specific memory mechanisms, but none of them interoperate. A team that switches agents loses its accumulated context. A team that uses multiple agents on the same repository must duplicate its memory. MemoryCustodian is an attempt to solve that problem from the repository side.
The timing matters. Coding agents are moving from novelty to daily driver. Teams are building long-running projects where continuity matters more than remembering every detail. The developers who maintain those projects are the ones who will decide whether MemoryCustodian’s approach is worth the curation cost.
The tool ships with a reproducible live evaluation, not a benchmark. The NightNotes demo can be run by anyone. The success criteria are explicit. The result is recorded as a reproducible flow, not a claimed metric. That is the right approach for a tool that asks teams to invest in a new discipline.
MemoryCustodian is not a smarter black box. It is a disciplined way to help coding agents carry a project forward instead of repeatedly relearning it. The question is whether the discipline is worth it. For long-running projects where the same decisions resurface across sessions, the answer may be yes. For short-lived experiments, the overhead may not justify the structure.
The tool’s design is a bet on a specific future: one where agents are smart enough to navigate structured memory but not smart enough to infer it from code alone. That future may last a year or a decade. Either way, MemoryCustodian is a useful test of what happens when teams treat agent memory as a governance problem rather than a capacity problem.