agent-carnet

Agent Carnet

A tiny CLI that gives you a shared markdown notebook on disk under .carnet/<category>/<slug>.md. Notes have a 30-day default lifespan that resets every time they are read or applied; useful ones survive, stale ones drift to .trash/ automatically.

Quick reference

# Save (always pass --summary and --agent claude-code)
echo "body content" | agent-carnet save deps/iconv-issue \
  --summary "iconv-esm v0.7 types broken — pin to v0.6" \
  --agent claude-code \
  --tags compat,esm

# Recall
agent-carnet find iconv               # search summaries (does NOT bump lifespan)
agent-carnet list                     # category-grouped overview, sorted by last_used
agent-carnet list --sort use_count    # most-applied notes first
agent-carnet show deps/iconv-issue    # read full content (bumps last_used; weak use signal)

# Mark as actually applied (strong use signal — bumps last_used + use_count)
agent-carnet used deps/iconv-issue

# Maintain
agent-carnet move <from> <to>
agent-carnet rm <path> --yes

When unsure of a subcommand's full flag set, run agent-carnet <command> -h (e.g. agent-carnet save -h, agent-carnet used -h). Each subcommand prints its own focused help — required arguments, options, and examples — without invoking filesystem operations.

When to save

Save proactively when you discover something worth preserving across sessions:

• Research findings that took effort to derive
• Non-obvious patterns / gotchas in the codebase
• Solutions to tricky problems
• Architectural decisions and the reasoning behind them
• In-progress work that may be resumed later

When to recall

Before starting related work or when context might exist:

• agent-carnet find <topic> — quick scan of summaries
• agent-carnet list <category> — browse a folder
• agent-carnet show <path> — actually read (resets last_used; only use when the content matters)

When to call used

Call agent-carnet used <path> after a carnet actually shaped your work:

• You applied the recorded fix and it solved the bug.
• You consulted the carnet before retrying a hypothesis and skipped a dead-end.
• You used the canonical name from a vocab carnet in new code instead of inventing your own.

used increments use_count — a durable importance signal that survives across sessions and lets future readers (and agent-carnet list --sort use_count) surface load-bearing notes.