MemoryCustodian

Product Introduction

1. Definition: MemoryCustodian is an open-source, local-first, cross-agent project memory management system for AI coding assistants. It is a developer tool that provides durable, structured memory for agents like Codex, Claude Code, and Gemini by storing project context as plain Markdown files within a code repository.
2. Core Value Proposition: MemoryCustodian exists to solve the problem of AI coding agents suffering from session amnesia, forcing developers to repeatedly paste project context into prompts. Its value proposition is delivering durable project memory with minimal context, enabling agents to remember architectural decisions, constraints, and rejected approaches across sessions without relying on a hosted service or bloating every interaction.

Main Features

1. Manifest-Driven Context Loading: The system uses a central manifest.md file to route context intelligently. Instead of loading all memory for every task, the agent reads only the brief.md and the specific files (like decisions.md, constraints.md) declared as relevant for the current task type (e.g., planning, implementation). This ensures minimal token usage and focused agent context.
2. Plain Markdown Memory Storage: All project memory—decisions, constraints, rejected approaches (do-not-use.md), and project briefs—is stored as human-readable Markdown files in a docs/memory/ directory. This enables version control with Git, code review workflows, and easy manual editing. The technology stack is intentionally simple, using only the filesystem and standard libraries for offline operation.
3. Structured Memory Modules & Atomic Operations: Memory is organized into optional, opt-in modules (rules/, profiles/, areas/) that remain out of context until explicitly enabled. The CLI enforces structure, validates entry length (e.g., 120-token guide for decisions), and provides preview-first, atomic operations for adding, forgetting (--mode soft or purge), compacting, and migrating memory, preventing corruption and ensuring data integrity.

Problems Solved

1. Pain Point: Agent Context Amnesia and Prompt Bloat. Each new AI agent session starts from scratch, requiring developers to manually re-explain project architecture, past decisions, and technical constraints, leading to inefficient, repetitive prompting and inconsistent outputs.
2. Target Audience: Developers and Teams using AI Coding Assistants (Codex, Claude Code, Gemini, Cursor, etc.); Technical Leads who need to enforce project conventions and architectural decisions across AI-assisted development; Open-Source Maintainers seeking to onboard contributors with consistent project context.
3. Use Cases: Onboarding a new AI agent to an existing codebase with complex history; Enforcing architectural decisions (e.g., "use JSON storage, not SQLite") across all future agent work; Documenting rejected approaches to prevent agents from re-proposing invalid solutions; Maintaining team knowledge about project quirks and preferences in a version-controlled, agent-readable format.

Unique Advantages

1. Differentiation: Unlike chat history or platform-specific instruction files, MemoryCustodian is agent-agnostic, local-first, and repository-centric. It avoids cloud dependencies, vector databases, and embedding models, focusing instead on deterministic, file-based memory that integrates with existing developer workflows like Git. Compared to pasting large context blocks, it provides structured, scoped access.
2. Key Innovation: The manifest-based context routing system combined with plain-text, version-controlled storage. This innovation separates the thin agent bootstrap (AGENTS.md) from the durable memory (docs/memory/), allowing for sophisticated, task-specific context loading while keeping the storage format simple, portable, and fully inspectable by both humans and machines.

Frequently Asked Questions (FAQ)

1. How does MemoryCustodian work with different AI coding agents like Codex and Claude? MemoryCustodian uses thin, agent-specific bootstrap files (e.g., CLAUDE.md, GEMINI.md) that instruct the agent to read the central docs/memory/manifest.md. The manifest, brief, and memory files are in plain Markdown, making them universally readable. The core CLI and memory protocol are agent-agnostic.
2. Is MemoryCustodian a cloud service or does it require an internet connection? MemoryCustodian is a local-first, offline tool. It operates entirely on your local filesystem using Python's standard library. No internet connection, cloud API, or external database is required for core memory reading and writing operations.
3. Can I edit the memory Markdown files manually, or do I have to use the CLI? Yes, you can and should edit the Markdown files manually. The CLI provides structure validation, safe atomic operations, and compaction, but the memory files are designed to be human-readable and editable like any other code documentation. The check command can validate manual edits.
4. What happens to my project memory if I stop using MemoryCustodian? Your memory remains as standard Markdown files in your docs/memory/ directory. Since there is no proprietary format or hosted service, you retain full ownership and access. You can simply stop using the CLI or bootstrap files; the knowledge documentation persists.
5. How does MemoryCustodian handle large codebases with many decisions? It uses scoped area-based memory (areas/ directory). Cross-cutting decisions stay in root files like decisions.md, while subsystem-specific knowledge lives in areas/frontend.md or areas/api.md. The manifest loads only the areas relevant to the current task, preventing context overload. The compact command helps archive or consolidate outdated entries.