Quick Start

Quick Start

Five minutes, entirely in a terminal. Everything here is also an MCP tool your agent can call; the terminal is just the easiest place to watch it.

Want a guided tour instead? logos demo runs a ninety-second walkthrough in a scratch vault and leaves your real one alone.

1. Record progress as you work

$ logos note demo "switched the cache to LRU"
noted — uncommitted until you checkpoint.

A note is cheap and temporary. It sits in sessions/demo/uncommitted.md until a checkpoint folds it in. If you leave out the project, Logos uses the one for the directory you are in.

2. Checkpoint where you stopped

$ logos checkpoint demo \
    --task "speed up the API" \
    --intent "p95 is over budget" \
    --state "LRU cache in, p95 down 40%" \
    --decided "LRU over LFU, because access is recency-skewed" \
    --failed "memcached sidecar — added 3ms per hop" \
    --verified "go test ./... passes" \
    --ran "go test ./..." \
    --file api/cache.go \
    --next "measure eviction rate under load" \
    --agent claude
checkpoint written: sessions/demo/_convos/_unattached/20261031-100852-claude.md
`logos resume` picks it up now — indexing only affects wider search.

--decided, --verified, --failed, --blocker, --ran, --question and --file can each be repeated. --failed is the field that matters most: it's the one thing the next agent cannot work out by reading the code.

3. Resume from anywhere

From another terminal, another day, or another agent (Cursor, Codex, a different model):

$ logos resume demo
# Context for: resume work on demo

## Where we left off

Last checkpoint by **claude**, just now.

**They were doing:** speed up the API
**Why:** p95 is over budget

**Verified by claude, not by you — safe to continue from:**
- go test ./... passes

**Decided:**
- LRU over LFU, because access is recency-skewed

**Already tried, didn't work:**
- memcached sidecar — added 3ms per hop

**Files touched:**
- api/cache.go

**Next step:** measure eviction rate under load

## Recorded since, not yet checkpointed
- switched the cache to LRU

In Claude Code you don't even have to ask. The plugin's SessionStart hook puts this in front of the model before your first message.

4. Ask before you repeat a mistake

$ logos tried "use memcached as a sidecar" --project demo
## This has been tried

One recorded dead end already bears on "use memcached as a sidecar".

- **memcached sidecar** — added 3ms per hop — tried by claude, just now
  try instead: in-process LRU

Before proposing this, say that it has been tried and what happened. If you
still think it is right, say what is different now — a dead end recorded under
other constraints is evidence, not a verdict.

The MCP tool for this is before_you_try. It searches dead ends in every project, not just this one.

5. Ask why a file looks the way it does

$ logos why api/cache.go
api/cache.go — 1 checkpoint(s)

─── recently · claude · demo
    while: speed up the API
    because: p95 is over budget
    ruled out:  memcached sidecar — added 3ms per hop
    decided:    LRU over LFU, because access is recency-skewed

6. Remember something durable

$ logos memory add "deploys go out on Tuesdays"
remembered — memory #1.

Memories are facts, preferences, people and procedures that outlive any one task. See Memory.

7. See it all on one screen

$ logos show demo
demo

Last checkpoint — claude, just now
  doing: speed up the API
  next:  measure eviction rate under load
  1 verified · 1 decision · 1 file touched

Not yet checkpointed — 1 note
  · switched the cache to LRU (just now)

Ruled out — 1 approach
  · memcached sidecar — added 3ms per hop (claude, just now)

· review queue: empty

Next: The Handoff Loop covers how an agent should use all of this during a real session.