Auto-Memory

Auto-memory is the agent-writable third tier of caliban's memory model. At the start of each session, caliban splices a per-project index file (MEMORY.md) into the system prompt. During the session, the agent uses two built-in tools — ReadMemoryTopic and WriteMemoryTopic — to read and write Markdown topic files that persist knowledge across sessions.

Directory layout

~/.local/share/caliban/projects/<sanitized-cwd>/memory/
  MEMORY.md              ← index, spliced into every session (≤ 200 lines / 25 KB)
  build-commands.md      ← topic file
  api-conventions.md     ← topic file
  deploy-checklist.md    ← topic file
  …

The <sanitized-cwd> slug is derived from the canonical workspace path (e.g. /Users/jf/dev/caliban → Users-jf-dev-caliban). Override the directory with CALIBAN_AUTO_MEMORY_DIRECTORY or CALIBAN_MEMORY_DIR.

The index file (MEMORY.md)

MEMORY.md is the only file loaded eagerly each session. It must stay under 200 lines / 25 KB so it fits comfortably inside the splice budget. Caliban bootstraps an empty MEMORY.md with a conventions block the first time the memory directory is accessed.

A typical index looks like:

# Memory index

- [build-commands](build-commands.md) — project: `cargo build --release`; binary lands in `target/release/`
- [api-conventions](api-conventions.md) — feedback: prefer the built-in HTTP helper over shelling out to curl
- [deploy-checklist](deploy-checklist.md) — project: run migrations before flipping the feature flag

HTML comments (<!-- … -->) in MEMORY.md are stripped from the spliced prompt but kept on disk. The auto-injected conventions block is wrapped in HTML comments for this reason — it stays on disk for authoring guidance but does not consume token budget.

Topic file format

Each topic file is a Markdown file with YAML frontmatter:

---
name: sprint-mode
description: "user prefers consolidated design proposals + spec + plan + implementation in one pass"
metadata:
  node_type: memory
  type: feedback
---

User prefers a single-pass workflow: design proposal, spec, plan, and
implementation delivered together without a human review checkpoint in
between.

Slug rules: non-empty, no path separators, no .., no leading ..

Memory types

The agent classifies each topic at write time. There is no automated classifier — the model is best positioned to judge what to save.

Built-in tools

Both tools are sandboxed to the memory directory — path traversal attempts are rejected at the tool level.

WriteMemoryTopic performs an atomic write:

1. Write topic body + frontmatter to <slug>.md.tmp.
2. Rename to <slug>.md (atomic on the same filesystem).
3. Rewrite MEMORY.md with an updated index line for the slug (same tmp-then-rename approach).

A crash between steps 2 and 3 leaves an orphan topic file. Run /memory rebuild-index to repair it.

Managing memory

There is no automatic pruning. Memories persist until manually removed.

Cross-references between topics

Topic bodies may contain [[slug]] cross-references, for example [[parity-gap-matrix]]. These are informational breadcrumbs — caliban does not auto-follow them. The agent can follow a reference by calling ReadMemoryTopic with the referenced slug.

Disable for CI

Set CALIBAN_DISABLE_AUTO_MEMORY=1 to drop the auto-memory tier from the splice and suppress the auto-memory skill. This guarantees identical system prompts regardless of on-disk memory state. --bare sets the same flag automatically.