Journey: Memory & Knowledge

You start a new chat in the same project tomorrow. Will your AI remember what it learned today? This journey covers how LeanCTX persists context across sessions: the Cross-Session Context Protocol (CCP), the project knowledge base, and how they get recalled automatically.

Two kinds of memory

Layer	Scope	Lives in	Recalled
Session (CCP)	one working session	sessions/<id>.json	auto on new session in same project
Knowledge	the whole project, forever	knowledge/<project-hash>/	on demand + auto at session start

Think of CCP as “what I was doing” and knowledge as “what’s true about this project.” Both are keyed by project, so a different repo gets its own memory.

Sessions — ctx_session / lean-ctx session

What it does: Tracks the current session’s tasks, findings, and decisions, and snapshots them so the next session in this project can resume.

lean-ctx session task "Refactor auth module [40%]"
lean-ctx session finding "JWT validation lives in auth/verify.rs"
lean-ctx session decision "Use session cookies, not JWT, for the web UI"
lean-ctx session status        # current session state
lean-ctx session save          # snapshot now
lean-ctx session load [id]     # restore a snapshot
lean-ctx session reset         # clear current session

Under the hood: ctx_session writes to sessions/<id>.json with an atomic write and updates sessions/latest.json as the pointer. The MCP tool supports more actions: snapshot, restore, resume, diff, verify, episodes, procedures.

Auto-restore — the key feature

When you start a new session in the same project, LeanCTX injects the prior session’s context (findings, decisions, touched files, progress) into the system prompt as the ACTIVE SESSION block. You don’t call anything, it happens because the MCP server detects the project and loads latest.json.

Golden output — the restored context block. This is the real, compact payload (~400 tokens) a new chat receives, also viewable on demand via ctx_session(action="status"):

SESSION v2610 | 354h 37m | 1953 calls | 90710600 tok saved
Task: Modified: 31 files changed, 1197 insertions(+), 780 deletions(-)
Root: …/Projects/lean-ctx
Findings (20): jetbrains.rs — deps: super::super::resolve_binary_path | setter.rs (227L) | schema.rs (1425L) | ctx_search.rs — pub struct CtxSearchTool;
Files (50): [F1 …/agents/jetbrains.rs map] [F33 …/config/setter.rs signatures] [F30 …/registered/ctx_read.rs full] [F26 …/core/protocol.rs full]

The [F1 … map] / [F33 … signatures] entries are persistent file references: the next read of F1 costs ~13 tokens because the agent already holds its compressed shape. This is what makes “start a new chat, it already knows where we were” work. If it doesn’t work, see Lifecycle & Maintenance → lean-ctx sessions doctor.

Managing saved snapshots — lean-ctx sessions

lean-ctx sessions list             # all saved snapshots
lean-ctx sessions show [id]        # inspect one
lean-ctx sessions cleanup [days]   # prune old snapshots
lean-ctx sessions doctor [--fix]   # diagnose/repair session restore

session vs. sessions: session (singular) records into the current session. sessions (plural, alias session-store) manages the store of saved snapshots. sessions doctor is your first stop if recall breaks.

Knowledge — ctx_knowledge / lean-ctx knowledge

What it does: A persistent, project-scoped knowledge base. Facts you (or your AI) store survive forever and are recalled across sessions, including by semantic search.

lean-ctx knowledge remember "Payments use Stripe; webhook secret in env STRIPE_WH"
lean-ctx knowledge recall "how do payments work"
lean-ctx knowledge search "stripe"
lean-ctx knowledge status          # counts, capacity
lean-ctx knowledge health          # integrity check
lean-ctx knowledge export --output kb.json
lean-ctx knowledge import kb.json --merge

Categories & confidence: facts carry a --category, optional --key, and a --confidence. High-confidence facts can be promoted to agent rules via lean-ctx export-rules (see Advanced & Integrations).

Recall modes (--mode): exact, semantic, hybrid, or auto. Semantic recall uses the knowledge embeddings (knowledge/<hash>/embeddings.json).

Under the hood: stored under knowledge/<project-hash>/knowledge.json. The MCP tool adds richer actions: relate/relations (link facts), consolidate (merge duplicates), timeline, rooms, and wakeup (the session-start recall bundle). Capacity is bounded by [memory.knowledge] max_facts (default 200), at capacity, doctor warns and consolidate reclaims space.

Gotchas — auto-learned mistakes

LeanCTX auto-detects recurring error patterns and stores them as gotchas (knowledge/<hash>/gotchas.json). View with lean-ctx gotchas list (alias bugs). Universal (cross-project) gotchas live in knowledge/universal-gotchas.json, gated by [boundary_policy].

Starting a session right — lean-ctx overview / ctx_overview

What it does: A task-relevant map of the project — the ideal first call in a new session. Combines structure, recent knowledge, and (optionally) task focus.

lean-ctx overview                       # general project map
lean-ctx overview "fix the login bug"   # task-contextualized
lean-ctx overview --json

ctx_overview is in the standard profile, so most setups expose it. It pulls the knowledge wakeup bundle when enable_wakeup_ctx = true (default), so your AI sees relevant prior facts immediately.

Context checkpoints — ctx_compress

For long conversations, ctx_compress creates a checkpoint that condenses what’s been seen so far, freeing context budget without losing the thread. The CLI equivalent is lean-ctx compress (--signatures keeps API surfaces). When you see [CHECKPOINT] in tool output, that’s LeanCTX prompting you to record progress via ctx_session(action="task").