Project Memory

Project Memory

Durable memory is Columbus's answer to context-file sprawl. Instead of scattered .md notes that drift and lie, memories are structured, queryable, evidence- linked, and drift-checked — and they live outside your repo. They are the context kind in the unified memory command, and like every durable-knowledge kind they are embedded and surface in semantic search.

Context kinds

A context entry has a --type: decision | pattern | failure | command | glossary.

Type	Use for
decision	A choice that was made and why
pattern	A recurring approach worth reusing
failure	Something that went wrong (and the fix)
command	A useful command / invocation
glossary	A project term and its meaning

Add a memory

$ columbus memory add context --type decision \
    --title "Default port is 8080" \
    --body "parseConfig falls back to 8080 when PORT is unset" \
    --evidence src/config.ts:4-6 \
    --ref symbol:parseConfig \
    --tag config
mem_001 [decision] Default port is 8080
parseConfig falls back to 8080 when PORT is unset
tags: config
evidence: src/config.ts:4-6
ref: symbol:parseConfig

• --evidence path:start-end — repeatable; anchors the memory to code.
• --ref file:<path> | symbol:<name> — repeatable; ties it to indexed entities.
• --tag — repeatable.

List and find

$ columbus memory list context
1 context entries
  mem_001 [decision] Default port is 8080

$ columbus search "fallback port" --kind memory   # semantic, by meaning

Memories are reachable from columbus search … --kind memory and --kind all, so an agent finds them — semantically — alongside code.

Drift detection

Evidence anchors are checked against the live code. When the code moves, the mismatch surfaces as a warning on the item, never fatal — the opposite of a stale .md file that silently lies. Re-anchor with memory update.

Update and remove

columbus memory update context mem_001 --body "…"                    # partial update
columbus memory update context mem_001 --add-ref file:src/server.ts  # add a link
columbus memory update context mem_001 --add-evidence src/config.ts:4-6
columbus memory remove context mem_001 --force                       # hard delete; id retired

Portable knowledge: export / import

A single document bundles memories plus epics, stories and tasks:

columbus export --out knowledge.json     # stdout by default
columbus import knowledge.json           # path or stdin

Vectors are not exported — columbus reindex rebuilds them. Useful for backups, sharing, or seeding a fresh checkout. See import & export.

Related

Command: memory · Tracking Work: Epics, Stories & Tasks · Never Stale: Live Reconstruction