MemoryCustodian: A Repo-Native Persistent Memory Store for Coding AIs

Curing the "Amnesia" of Coding AIs

If you've been using coding assistants like Claude Code, Codex, or Gemini for any length of time, you've probably encountered a frustrating problem: the AI can't remember project context. In one session you told it "this module must use async implementation" or "we've already rejected the Redis approach," but in the next session, it starts suggesting those very same rejected solutions all over again.

The root cause of this "amnesia" lies in the fact that large language models have no persistent memory across sessions. Every conversation starts from scratch unless you manually stuff all the background information back into the prompt. This is dictated by how LLMs work: during each conversation, the model can only process information within a fixed-length "context window" — currently ranging from 128K to 200K tokens for mainstream models. This window functions like the model's "working memory," and once a session ends, everything in it gets cleared. Unlike the human brain, which automatically encodes important experiences into long-term memory, LLMs must re-understand all context from the beginning every time.

And cramming the entire project history into the context window is both expensive and inefficient — it also dilutes the model's attention on the current task. Token-based billing means longer prompts directly increase API costs, and research has shown that when context is too long, the model's attention to information in the middle drops significantly (the "lost in the middle" phenomenon).

The open-source tool MemoryCustodian, which recently appeared on Product Hunt (ranking #6 that day with 162 upvotes and 25 comments), targets precisely this pain point. Its core proposition can be summed up in one sentence: give coding agents a "repo-native" persistent memory.

What Is "Repo-Native Memory": The Philosophy of Memory as Code

MemoryCustodian's design philosophy is fundamentally different from most memory solutions on the market. Current mainstream AI memory solutions typically rely on vector databases (such as Pinecone, Weaviate, ChromaDB, etc.), converting text into high-dimensional vector embeddings and using cosine similarity calculations between vectors for semantic retrieval. Building on this, RAG (Retrieval-Augmented Generation) architectures chunk and vectorize knowledge base documents, retrieving the most semantically relevant fragments to inject into prompts when users ask questions. The advantage of this approach is high automation and the ability to handle large-scale knowledge bases, but the downsides are opaque retrieval results, potential noise introduction, and typical dependence on externally hosted services.

MemoryCustodian takes a completely different path: it doesn't rely on any hosted service or external vector database. Instead, it stores AI memory directly as plain Markdown files in your code repository.

Specifically, key project information — technical decisions, constraints, rejected approaches, and project context — gets recorded as Markdown documents that live alongside your source code in the repo. This brings several immediate benefits:

• Auditable: Memory content exists as plain text, so any team member can review what the AI remembers just like reviewing code;
• Versionable: Memories are committed with Git, so you can track their evolution history and roll back incorrect records;
• Shareable: Team members get the same project memory simply by cloning the repository, with no extra configuration needed;
• Deletable: Unneeded memories can be deleted just like deleting code — transparent and controllable.

This "memory as code" approach transforms AI's implicit context into explicit, manageable project assets. Compared to solutions that lock memory in a cloud-based black box, it gives developers complete control.

Precise Loading of Relevant Memories via the Manifest Mechanism

Simply storing memories isn't enough. If you feed all memories to the model every time, you're back to the "prompt bloat" problem. MemoryCustodian's solution is a manifest mechanism: it loads only the memory fragments truly relevant to the current task, rather than injecting everything at once.

The manifest concept has a long tradition in software engineering. Android's AndroidManifest.xml declares the permissions and components an app needs, npm's package.json lists project dependencies, and Kubernetes YAML manifests describe resources to deploy. MemoryCustodian borrows the same idea: an index file declares "which memory fragments need to be loaded for the current context," enabling on-demand loading rather than bulk injection. While this explicit declaration approach requires some manual maintenance, it delivers complete predictability — developers know exactly what information the model will see.

This design is quite critical. It means that no matter how large your project memory grows, the content actually entering the context window stays lean, striking a balance between "remembering enough" and "not being bloated." This is also what distinguishes it from simply maintaining a large README or CLAUDE.md file.

Local-First and Cross-Agent: Solving Privacy and Tool Lock-In

Two other core selling points of MemoryCustodian are local-first and cross-agent.

Local-First is a software design philosophy systematically articulated by Ink & Switch labs in 2019. Its core principles include: data is primarily stored on the user's local device, software works offline, and users have complete ownership of their data. This philosophy is a reaction to the past decade's "cloud-first" trend — when all data is stored in the cloud, users effectively lose control over their own data, facing risks of service provider shutdowns, API changes, and privacy breaches.

In MemoryCustodian's context, local-first means your project decisions and architectural constraints — sensitive information — never get uploaded to any third-party server. For enterprise teams that prioritize data privacy and compliance, this is especially important — memories always stay in your own repository, protected by your own access control policies.

Cross-agent addresses the problem of tool fragmentation. Between 2024-2025, the coding AI assistant market has seen explosive growth and high fragmentation: Claude Code (Anthropic) excels at agentic workflows with autonomous multi-step programming tasks; Codex CLI (OpenAI) emphasizes local sandbox execution; Gemini Code Assist (Google), GitHub Copilot, Cursor, Windsurf, and other tools each have their own strengths. Each tool has developed its own memory/context management scheme (like Claude's CLAUDE.md, Cursor's .cursorrules), but these schemes are incompatible with each other.

Today you might use Claude Code, tomorrow someone on your team prefers Codex, and another is trying Gemini. Traditional solutions are often tied to a specific tool's memory system, and switching tools means losing memory. Since MemoryCustodian uses standard Markdown as its medium, theoretically any coding agent that can read repository files can reuse the same memory, avoiding vendor lock-in.

A Pragmatic Engineering Choice

From a technical standpoint, MemoryCustodian doesn't chase trendy vector retrieval or complex RAG architectures. Instead, it chooses the simplest, most transparent approach — text files plus a manifest index. This may seem "simple," but it's actually a pragmatic engineering judgment: for project memory in coding scenarios, readability, auditability, and Git compatibility often have more practical value than the elegance of semantic retrieval.

Behind this choice lies an important engineering insight: project memory for coding differs from general-purpose knowledge base retrieval. Technical decisions in a project are typically limited in number (tens to hundreds), highly structured, and strongly associated with specific modules or functional domains. At this scale and with these characteristics, precise manual indexing is actually more reliable than fuzzy semantic matching — you don't want the model loading incorrect decision records due to subtle differences in vector similarity.

Developers can see at a glance what the AI remembers, manually correct it, and incorporate it into code review workflows — this certainty and controllability is precisely what black-box memory solutions lack.

Use Cases and Limitations

This tool was developed by Zekun Wang. It's open-source, free, and categorized under developer tools and artificial intelligence. It's best suited for:

1. Medium to large projects requiring long-term maintenance with complex context;
2. Teams collaborating and wanting to share a unified set of AI context;
3. Users sensitive to data privacy who don't want to hand project information to hosted services;
4. Developers using multiple coding AIs who want memory to be reusable across tools.

Of course, the plain text plus manual manifest approach has its trade-offs. When memory entries become very numerous, organizing and retrieving them may require some manual maintenance effort; compared to automated semantic retrieval, it relies more on human judgment about "what to remember and what to load." This is both its transparency advantage and its potential scaling bottleneck — when project memories grow from dozens to hundreds of entries, maintaining the manifest itself may become a burden, potentially requiring hierarchical organization or semi-automated index generation mechanisms as supplements.

Conclusion

As coding agents increasingly become part of development workflows, "AI memory management" is evolving from an add-on feature into core infrastructure. MemoryCustodian provides a clear-thinking, opinionated answer: memory shouldn't be hidden in a cloud-based black box but should live in the repository like code — audited, versioned, and shared by the team.

Among the many memory solutions pursuing complex architectures, its restrained "memory as code" design stands out as refreshingly different. For developers who work with coding AIs daily yet struggle with their "forgetfulness," this might be worth a try.