MemoryCustodian Guide: How to Use It, Best Prompts & Use Cases (2026)
TL;DR: This MemoryCustodian guide covers what the tool does, how to set it up in five minutes, and how to use it to give Claude Code, Codex, and Gemini persistent, repo-native memory so they stop forgetting your project between sessions.
What Is MemoryCustodian? (And Why Everyone's Talking About It)
MemoryCustodian is a free, open-source tool that launched on Product Hunt today, built by developer Zekun Wang. It gives AI coding agents — Claude Code, OpenAI Codex, Gemini, and generic agent workflows — durable, project-level memory. Instead of storing context in a hosted database or stuffing it into an ever-growing instructions file, MemoryCustodian keeps memory as plain Markdown files inside your repo itself. Decisions, constraints, rejected approaches, and project context become part of your codebase — reviewable, versioned, and shareable through the same Git workflow you already use.
If you've spent any time with a coding agent, you already know the problem this solves. Every new session starts blind. You explain your architecture, your naming conventions, the library you already tried and rejected — and the next session, the agent has forgotten all of it. Teams end up either re-explaining the same context over and over, or pasting increasingly bloated instructions into every prompt, which burns tokens and dilutes the agent's focus.
This MemoryCustodian tutorial exists because the tool launched less than 24 hours ago and there's no comprehensive resource yet. It's already sitting at #3 on Product Hunt's daily leaderboard, and the pain point it addresses — agent amnesia — is one of the most common complaints in developer communities building with AI agents.
MemoryCustodian's core mechanism is a manifest system. A lightweight manifest classifies each incoming task — planning, implementation, artifact work, or maintenance — and deterministically loads only the memory files relevant to that category. Memory scales with your project without bloating every single prompt. Because it's local-first and cross-agent, it works whether you're using Claude Code today and switch to Codex tomorrow — the memory travels with the repo, not with a specific tool or vendor.
Who Is MemoryCustodian For?
MemoryCustodian is built for anyone running repeated AI coding agent sessions against the same codebase and tired of re-establishing context every single time. It's especially valuable once a project gets complex enough that "just re-explain it" stops being a five-second tax and starts being a real productivity drain.
Ideal users include:
- Solo developers and indie hackers juggling multiple side projects with different AI agents
- Engineering teams that hand tasks between human developers and coding agents
- AI-native agencies (like dev shops building on Claude Code or Codex) managing multiple client repos
- Freelancers who need to keep client-specific constraints straight across projects
- Anyone who has typed "we already tried that, don't suggest it again" more than once this week
Key Features of MemoryCustodian
Repo-Native, Plain-Text Memory
No hosted service, no opaque database. Memory lives as Markdown files in your repository, which means it's reviewable in a pull request, diffable, and portable — it moves with the repo, not with an account.
Selective Loading via Manifest
Rather than injecting your entire project history into every prompt, MemoryCustodian's manifest maps task categories to specific files. Planning and implementation tasks load decisions.md, constraints.md, and do-not-use.md by default; lighter tasks skip the extra context entirely.
Cross-Agent Compatibility
MemoryCustodian explicitly supports Codex, Claude Code, Gemini, and generic coding-agent workflows. Switch tools mid-project and the memory persists — you're not locked into one vendor's context system.
Explicit Forgetting and Correction
Memory isn't write-only. The system supports updating, correcting, and safely removing entries, so stale decisions don't linger and confuse future sessions.
How to Get Started with MemoryCustodian in 5 Minutes
- Install it. Clone or add MemoryCustodian to your project by following the setup instructions at the official GitHub repo (search "MemoryCustodian GitHub" or find it under maker Zekun Wang's account).
- Initialize the memory structure. This creates the core Markdown files — decisions.md, constraints.md, do-not-use.md — plus the manifest that maps task types to files.
- Seed your first entries. Don't wait for a "big" decision. Log naming conventions, rejected libraries, and environment quirks — the small stuff is what agents forget fastest.
- Point your agent at the manifest. Whether you're running Claude Code, Codex, or Gemini, tell it to check the manifest before starting a new task.
- Run a real task and correct it. Watch the agent load only relevant memory files instead of your whole project history. Every correction you make becomes a new memory entry for next time — the system compounds.
7 Best Use Cases for MemoryCustodian
1. Solo Developer Context Switching
If you're bouncing between three side projects with the same coding agent, MemoryCustodian means you never have to re-explain each project's architecture from scratch when you switch back.
2. Team Handoffs
A teammate picking up a task an agent started can read exactly what was decided and why, instead of reconstructing the reasoning from Slack threads or old chat logs.
3. Rejected-Approach Tracking
This might be the single highest-leverage use case: stop your agent from re-suggesting a library or pattern you already tried and abandoned three sessions ago.
4. Client Project Memory for Agencies
Agencies running multiple client repos can keep client-specific constraints — compliance rules, brand voice, tech stack limits — versioned alongside the code, so nothing gets mixed up between clients.
5. Onboarding New Engineers
New hires can read decisions.md instead of pinging five people to understand "why is it built this way." It becomes a living, agent-maintained architecture doc.
6. Multi-Agent Workflows
Claude Code and Codex can share the same memory files on the same repo, so switching tools mid-project doesn't reset context back to zero.
7. Long-Running Refactors
Track partial progress and rationale across a refactor that spans weeks of agent sessions, so nobody — human or AI — loses the thread halfway through.
5 Copy-Paste Prompts for MemoryCustodian
Here are five of the best MemoryCustodian prompts to get real memory files built fast. Paste these directly into your coding agent.
Prompt 1: Bootstrap Your Decisions Log
Scan this repository's codebase, commit history, and any existing README or docs.
Create a decisions.md file for MemoryCustodian that lists every major architectural
decision you can infer — framework choice, folder structure, state management,
database choice — with a one-line rationale for each.
Prompt 2: Bootstrap Your Constraints File
Create a constraints.md file for MemoryCustodian. Interview me about this project's
non-negotiable rules — coding style, security requirements, libraries we will never
use, performance budgets — one question at a time, and add each answer as a
formatted entry.
Prompt 3: Log a Rejected Approach
We just decided not to use [APPROACH/LIBRARY/PATTERN] for [REASON]. Add an entry
to do-not-use.md explaining what was rejected, why, and what we're using instead,
so no future session suggests it again.
Prompt 4: Generate the Task-Category Manifest
Create a MemoryCustodian manifest that maps task categories (planning,
implementation, artifact work, maintenance) to the memory files each category
should load. Explain your reasoning for each mapping.
Prompt 5: End-of-Session Memory Update
Before we end this session, summarize any new decisions, constraints, or rejected
approaches that came up. Write them as properly formatted MemoryCustodian entries
and tell me exactly which file each one belongs in.
MemoryCustodian vs. Cursor/Claude Code Built-In Memory: Which Should You Use?
Tools like Claude Code and Cursor increasingly ship their own project-instructions files (think CLAUDE.md-style context files). Those work fine for static, top-level rules but tend to become one giant file that gets pasted into every prompt regardless of relevance — which is exactly the bloat problem MemoryCustodian was built to solve.
MemoryCustodian isn't a replacement for those files so much as a more structured, selectively-loaded layer on top: decisions, constraints, and rejected approaches live in their own files, loaded only when the task category calls for them. If your project is small, a single instructions file is probably still simpler. Once you're running multiple agents against a complex, long-lived codebase, the manifest-based approach starts paying for itself.
How to Make Money with MemoryCustodian
1. Sell a Setup Guide or Template Pack
Package a polished walkthrough — like this one — plus ready-to-use decisions.md, constraints.md, and do-not-use.md templates as a $9–$19 digital product. Developers who don't want to architect a memory schema from scratch will pay for a head start.
2. Offer "Agent Memory Audits" as a Service
For $150–$500, review a client's or team's coding-agent workflow and set up their MemoryCustodian structure, tuned to their actual stack and constraints. This is a natural upsell for any agency already doing AI-agent consulting.
3. Build Stack-Specific Starter Kits
Pre-written memory templates for popular stacks — Next.js + Supabase, Django, a specific SaaS boilerplate — sold as a $15–$29 add-on pack. First-mover guides on brand-new tools tend to rank and sell precisely because nothing else exists yet.
Frequently Asked Questions About MemoryCustodian
Is MemoryCustodian free?
Yes. MemoryCustodian is free and open source, available on GitHub. There's no hosted service or subscription — memory lives locally as Markdown files in your own repo.
Is MemoryCustodian safe to use?
Since memory is stored as plain text files inside your own repository, you have full visibility and control over what's stored. Nothing is sent to a third-party hosted database, which makes it a reasonable fit for teams with data-sensitivity concerns.
What is MemoryCustodian best for?
It's best for developers and teams running repeated AI coding agent sessions against the same codebase who are tired of re-explaining architecture, constraints, and past decisions every session.
How does MemoryCustodian compare to a single CLAUDE.md or instructions file?
A single instructions file gets pasted into every prompt regardless of relevance, which bloats context as a project grows. MemoryCustodian's manifest selectively loads only the memory relevant to each task category, so it scales better on larger, longer-lived projects.
Can beginners use MemoryCustodian?
Yes. The core workflow — initialize the memory files, seed a few entries, point your agent at the manifest — takes about five minutes, and the copy-paste prompts in this guide handle most of the setup work for you.
Final Verdict
MemoryCustodian addresses a problem nearly every AI coding agent user has hit: the agent forgets everything the moment the session ends. By keeping memory as plain, versioned Markdown inside the repo — and loading it selectively instead of dumping it into every prompt — it turns tribal project knowledge into something git-trackable and agent-readable at the same time.
It's free, open source, and takes about five minutes to set up. If you're running Claude Code, Codex, or Gemini against any codebase you touch more than once, this is worth trying today while it's still new.
Want the complete MemoryCustodian prompt pack + monetization playbook? I put together a full guide with 10 copy-paste prompts, all 7 use cases mapped out, and a step-by-step monetization playbook. Grab it on Gumroad for $9 →
Published: 2026-07-29 | Updated: 2026-07-29
Top comments (0)