Core Concepts

Core Concepts

The vault

A folder of markdown, ~/logos by default (set LOGOS_VAULT to move it). Everything durable lives here as plain files you can read, edit, grep and put under git. Inside it, .logos/index.db is a SQLite cache for search. Delete .logos/, run logos index, and nothing is lost. See The Vault for the layout.

Projects

Everything is scoped to a project, so one repository's facts don't turn up in another's. The project name comes from the directory you are in: the repository root's folder name, and linked git worktrees count as the same project. Hooks compute it the same way; logos project-name [dir] prints what it would be.

• logos show --projects lists the projects it has detected.
• logos project <name> shows a project's dossier.
• logos project rename <old> <new> renames a project and moves its history with it. Add --merge to fold it into an existing project.
• logos config deny, run inside a repository, keeps Logos out of it entirely.

Working notes

note / note_progress writes one line of progress. Notes are deliberately cheap. They collect in sessions/<project>/uncommitted.md until the next checkpoint folds them in. resume shows notes that were never checkpointed under "Recorded since, not yet checkpointed", so an agent that crashed mid-session still leaves a trail.

Checkpoints

A checkpoint is the durable record of where work stopped: one markdown file per checkpoint. Its fields:

Field	What goes in it
task	What was being attempted
intent	Why the task matters. Later checkpoints with the same task inherit it
state	Where things actually stand, including anything half-finished
decisions	What was chosen and why: "X, because Y"
failed	What was ruled out and why. The most valuable field
verified	Only what was demonstrated, with the command that showed it. Belief goes in state
commands	The build/test/lint commands actually run
blockers	What is known broken or unfinished, and what it blocks
questions	What is still open
files	Files touched; this is what why <file> joins on
next	The single next step for whoever picks this up

verified and failed are kept separate on purpose. "I believe it works" and "I ran it and it works" are different claims, and the next agent should be able to tell them apart.

A handoff is a checkpoint with a named successor (--handoff <agent> on the CLI, or the handoff tool with to).

Conversations

Checkpoints are grouped by the host session that wrote them: sessions/<project>/_convos/<host-session-id>/. Checkpoints written outside any host session, such as from the CLI, go in _convos/_unattached/, and each of those counts as its own conversation.

• logos resume <project> resumes the project. At a terminal it first asks which conversation you mean.
• logos resume <project> <id-or-name> resumes one conversation, matched by its folder id, a checkpoint, or part of its intent.
• logos migrate sessions moves checkpoints from older versions (flat files in sessions/<project>/) into conversation folders, and tells you how many it moved.

Dead ends (rulings)

Each failed entry becomes a recorded dead end. Plain prose works. A structured line is matched more precisely and renders better:

route: memcached sidecar | observation: added 3ms per hop | layer: design |
degree: contradicted | action: abandon | alternative: in-process LRU

Key	Values
layer	implementation, design, environment, dependency, requirement
scope	local, version-bound, general
degree	contradicted, partial, inconclusive, unstable
action	retry, change-method, narrow-scope, abandon

Dead ends reach the next agent three ways:

1. resume, through the checkpoint itself.
2. before_you_try / logos tried, which searches every project in the vault.
3. In Claude Code, the pre-edit hook adds a one-line note beside an edit to a file that a dead end names. This happens once per file per session, and it never blocks the edit.

A recorded failure is evidence, not a veto. Rulings from another project are flagged as possibly not applying.

logos ledger [project] writes a project's long-term history, built from every checkpoint, to sessions/<project>/ledger.md: decisions still in force, ones superseded, dead ends and open questions.

Memories

Facts, preferences, people, context and procedures that outlive any one task. They live in memories/<kind>.md and the folders beside it. An agent's remember can be queued for your review instead of written straight away. See Memory.

Receipts

Every write returns a receipt as its first line, such as ✓ Logos · checkpoint saved to logos, and agents are told to repeat it to you. Hosts collapse tool results to a grey line, and a memory layer you cannot see working looks exactly like one that is broken. logos config announce on|quiet|off sets how loud this is.

Context packs and budgets

resume and context don't return everything. They spend a token budget (default 4000) on what matters most, cite each source, and say what they left out:

_Context budget: ~1468 of 4000 tokens (checkpoint 1414, memories 54)._
_Left out for space (a larger budget brings them in): …_

They also choose a time window from the gap since your last checkpoint. Pass since: all to the MCP tool to see everything, or a larger budget to fit more.