Persistent project memory

Memory that survives the chat.

Tracebook gives Codex, Claude Code, and other coding agents a local, evidence-backed memory of your project—without adding a server, database, or files to your business repositories.

Install in two commands Run the cross-session demo
Plain Markdown Evidence gated No server or API key
refund-retry-policy.md

---

knowledge_id: refund-retry-policy

status: current

version: 2

---


## Current

Refunds retry at most twice

with a 3-second timeout.


Evidence: src/refunds.py:L18

The problem

A new chat should not mean a new investigation.

Source code survives the session. The reasoning around it often does not. Tracebook preserves the conclusions worth reusing—and keeps the evidence needed to challenge them later.

01

Stop rediscovery

Load focused conclusions before repository work instead of reopening the same architecture, incidents, and business rules.

02

Keep claims traceable

Every current fact names its supporting source. Health checks flag missing or newer evidence instead of silently trusting stale notes.

03

Keep the repo clean

Knowledge stays under ~/.tracebook. No memory folder, daemon, vector database, hook, or configuration is written into business repositories.

One task, two sessions

The agent carries verified context forward.

Tracebook is an Agent Skill with a deterministic local runner. The agent makes semantic judgments; the runner owns identity, storage, history, transactions, and health checks.

Before work

Load only what matters

The active project is resolved, then bounded retrieval returns relevant current knowledge with source-project identity.

After verification

Capture durable conclusions

Raw transcripts and guesses are rejected. Stable IDs, evidence, scope, lifecycle state, and version history make changes explicit.

Next session

Start from evidence

The next agent retrieves the current conclusion first, then checks the cited source when the task needs deeper verification.

Memory with governance

Not a transcript dump.

A memory can be current, pending, deprecated, superseded, or historical. Writes are transactional; normal reads use committed snapshots.

  • Project, domain, and reusable pattern scopes
  • Stable project IDs across clones of one Git remote
  • Explicit cross-project systems and relations
  • Light, regular, and deep health workflows
Knowledge lifecycle
CURRENT     applies now
   │
   ├── revise → version history retained
   │
   ├── SUPERSEDED → replacement linked
   │
   └── DEPRECATED → no longer applies

PENDING     known, not yet confirmed
HISTORICAL  available only on request

Stable release · v4.0.7

Install, restart your agent, keep working.

Python 3.10 or newer is required. The documented workflow is verified in CI on Ubuntu and Windows with Python 3.10 and 3.13.

Codex

Terminal
codex plugin marketplace add tydandou/tracebook --ref v4.0.7
codex plugin add tracebook@tracebook

Claude Code

Terminal
claude plugin marketplace add tydandou/tracebook
claude plugin install tracebook@tracebook

Choose the right memory model

Tracebook is deliberately narrow.

It is not a task manager, semantic search engine, or replacement for host instruction files. These practical comparisons explain where the boundary helps—and where another approach fits better.

Instructions

Tracebook vs CLAUDE.md and AGENTS.md

Stable instructions and evolving project knowledge solve different problems. Most serious projects benefit from both.

Read the comparison → Storage

External memory vs repo-local memory

Choose between repository reviewability and strict separation from business code, or combine them intentionally.

Read the comparison → Retrieval

Markdown governance vs vector memory

Deterministic evidence-backed facts are different from fuzzy semantic retrieval over large corpora.

Read the comparison →
Local-firstInspectable Markdown on your disk
Zero servicesNo server, daemon, database, or API key
Cross-sessionCurrent conclusions survive the chat
Apache-2.0Open source and free to use

Give your agent a project memory

Stop paying the rediscovery tax.

Run the isolated demo, inspect the Markdown it creates, then decide whether Tracebook belongs in your regular coding workflow.

Run the demo View source on GitHub