Memory

Make CrabCode remember your preferences, project context, and long-term cross-session experience.

What it is

CrabCode's "memory" is two complementary mechanisms:

CRABCODE.md instruction files (you write, you own, you decide whether they go into git) — merged into the system prompt at every session start
Auto-memory (managed by CrabCode itself) — long-term cross-session notes injected on demand

Both are on by default and independent of each other.

`CRABCODE.md` instruction files

CrabCode merges these markdown files at startup in the order below (later entries have higher priority):

Scope	Path	Use
User	`~/.crabcode/CRABCODE.md`	Cross-project preferences (who you are, how you collaborate)
Project	`<repo>/CRABCODE.md` or `<repo>/.crabcode/CRABCODE.md`	Team-shared project knowledge (architecture, conventions); committed
Project (per-topic rules)	`<repo>/.crabcode/rules/*.md`	Rule files split by topic, loaded individually
Local	`<repo>/CRABCODE.local.md`	Personal project notes; gitignored

CrabCode walks from cwd up to the filesystem root; files closer to cwd win. Inside any of these files you can include other files via @./path, @/abs/path, or @~/home/path.

View / edit

shell

/memory
/memory

Lists every memory file across scopes; selecting one opens it in $EDITOR or $VISUAL.

Bootstrap with `/init`

If the repo root has no CRABCODE.md, run /init and CrabCode will scan the codebase and draft one for you. Review, edit, commit.

Auto-memory

CrabCode also maintains a structured cross-session memory store under:

shell

~/.crabcode/projects/<sanitized-git-root>/memory/
~/.crabcode/projects/<sanitized-git-root>/memory/

It contains:

MEMORY.md — the index entry (injected at startup, capped at 200 lines / 25 KB; truncated past that)
Per-topic markdown files, each with a frontmatter type: set to one of user / feedback / project / reference

The agent reads and writes this directory on its own; you don't manage it by hand. To turn it off:

json

{ "autoMemoryEnabled": false }
{ "autoMemoryEnabled": false }

Or one-off at launch:

bash

CRABCODE_DISABLE_AUTO_MEMORY=1 crabcode
CRABCODE_DISABLE_AUTO_MEMORY=1 crabcode

To relocate the auto-memory directory (user / local / managed scope only):

json

{ "autoMemoryDirectory": "~/notes/crabcode-memory" }
{ "autoMemoryDirectory": "~/notes/crabcode-memory" }

Let the model write

Just say it:

shell

remember: this project uses pnpm, not npm
remember: this project uses pnpm, not npm

The model decides whether to write into CRABCODE.md or into auto-memory.

Limits and caveats

40 KB per file cap: any individual CRABCODE.md / memory file beyond 40 000 chars stops being loaded
MEMORY.md index 200 lines / 25 KB cap: truncated past that — keep the index terse
No secrets: memory ships in every model request — never write API keys or passwords there
projectSettings can't change autoMemoryDirectory: setting it inside the repo's .crabcode/settings.json is ignored (otherwise a malicious repo could point memory at ~/.ssh and gain silent write access via the auto-memory write carve-out)
--bare / CRABCODE_SIMPLE=1 skips both CRABCODE.md auto-discovery and auto-memory