c2m

c2m is a git-native memory system for coding agents.

It stores durable repository knowledge under .agents/memory/ as a hierarchy of documents. Agents append observations over time, and an LLM periodically compacts those observations into updated summaries. The result is memory that stays local to the repo, survives branch switches, can be reviewed in git, and can be shared across tools like Codex CLI and Claude Code.

For the detailed format and design spec, see overview.md.

Overview

c2m organizes memory into two explicit roots:

• api for user-facing behavior, usage guidance, examples, and integration notes
• dev for implementation details, architecture, workflow, and engineering guidance

Each document has:

• a markdown summary that represents the current compacted state
• an append-only event log for recent knowledge not yet compacted
• optional child documents for more focused topics

The CLI is the interface. Agents should not edit .agents/memory/ directly.

Patterns And Goals

c2m is built around a few specific ideas:

• Git-native memory. Knowledge lives in normal repo files instead of an external database.
• Append first, restate later. Agents record facts quickly with add; compaction rewrites them into cleaner current-state summaries.
• Reviewable state. Memory is visible, diffable, branchable, and recoverable.
• Agent-oriented structure. Many small docs are preferred over a few large ones.
• Merge resilience. Conflicting heads are handled with merge-on-read until the next compaction.
• Simple concurrency. Writes are serialized with one repo-local lock, assuming parallel work happens in separate worktrees.

This is not trying to be a generic document store or a hidden retrieval layer. The goal is durable repository memory that works well inside normal software workflows.

Quick Start

Initialize c2m at the root of a git repo:

c2m init

That creates:

• .agents/memory/
• the initial api and dev root documents
• AGENTS.md and CLAUDE.md
• repo-local Codex and Claude skill files

Then add knowledge:

c2m add dev/architecture/auth "Opaque session tokens are required for immediate revocation."
c2m add api/authentication "Users can sign in with email and password."

Find and read it:

c2m ls dev
c2m search "session revocation"
c2m grep -r "opaque.*revocation" dev
c2m cat dev/architecture/auth

Compact it when summaries need to be refreshed:

c2m compact dev/architecture/auth --force

Usage

Common commands:

c2m init
c2m add <path> <content>
c2m cat <path>
c2m ls [path]
c2m search <query>
c2m grep [flags] <pattern> [path...]
c2m compact [path]
c2m mv <old-path> <new-path>
c2m rm [-r] <path>
c2m doc <api|dev>

Notes:

• init must be run inside a git repository.
• ls is recursive.
• search runs live against rendered documents and returns relevance-ranked matches.
• grep is line-oriented regex search over the same rendered views.
• compact requires model configuration in .agents/memory/settings.yaml.

Examples

Initialize memory for a repo:

c2m init --model gpt-5-codex

Add implementation guidance:

c2m add dev/build "Use `go test ./...` before merging CLI changes."

Add user-facing behavior:

c2m add api/search "Search ranks rendered documents by relevance and grep supports regex."

List everything under one subtree:

c2m ls api

Read one document as JSON:

c2m cat dev/architecture/auth --format json

Search semantically-ish across rendered docs:

c2m search "revoked sessions"

Run regex grep across a subtree:

c2m grep -r -n "revok(e|ed|ation)" dev

Bulk-ingest repository knowledge with Codex:

c2m upload dev cmd/c2m/*.go internal/**/*.go

Force compaction of one document:

c2m compact api/authentication --force

Workflow

A good default workflow for agents is:

1. c2m doc api or c2m doc dev to orient on the root.
2. c2m ls, c2m search, or c2m grep to find the relevant document.
3. c2m cat to read the smallest useful node.
4. Do the actual engineering work.
5. c2m add any durable new knowledge.
6. c2m compact when summaries have drifted or event logs have grown.

Storage Model

The storage root is .agents/memory/.

Each document is represented on disk by sequence-numbered files such as:

0000004_6db6851_overview.md
0000004_6db6851_events.jsonl

The active summary is markdown with front matter. The active events file is JSONL. Older files are retained for merge safety and debugging according to retention settings.

Tooling Integration

c2m init installs repo-local guidance for both Codex and Claude:

• AGENTS.md
• CLAUDE.md
• .agents/skills/c2m-memory/SKILL.md
• .claude/skills/c2m-memory/SKILL.md

The intention is that agents in the repo will discover and use c2m automatically rather than treating it as an optional side system.

Development

Build the CLI from the repository root:

go build ./cmd/c2m

Run tests:

go test ./...