From a6545c4c1801a86e2cb534c225dcd053ab4617b7 Mon Sep 17 00:00:00 2001 From: Coder8124 Date: Tue, 3 Nov 2026 21:22:15 -0800 Subject: [PATCH] The README is a short front page that sends readers to the wiki --- README.md | 230 +++++++++++++++++++++--------------------------------- 1 file changed, 88 insertions(+), 142 deletions(-) diff --git a/README.md b/README.md index 492049e..844da96 100644 --- a/README.md +++ b/README.md @@ -1,180 +1,126 @@ +
+ # Logos **When one coding agent stops, the next one continues the work.** -![Claude Code checkpoints, Codex resumes, opencode continues](docs/demo.gif) +[![Release](https://img.shields.io/github/v/release/Coder8124/logos?color=00392F)](https://github.com/Coder8124/logos/releases) +[![npm](https://img.shields.io/npm/v/@noeton/logos?color=00392F)](https://www.npmjs.com/package/@noeton/logos) +[![License](https://img.shields.io/badge/license-Apache%202.0-00392F)](LICENSE) -| [Setup](SETUP.md) | [Docs](https://github.com/Coder8124/logos/wiki) | [Benchmark](docs/continuity-benchmark.md) | [Agent guide](systemmd/LOGOSPROMPT.md) | [Contributing](CONTRIBUTING.md) | [Site](https://coder8124.github.io/logos/) | -| --- | --- | --- | --- | --- | --- | +[Docs](https://github.com/Coder8124/logos/wiki) · [Quick Start](https://github.com/Coder8124/logos/wiki/Quick-Start) · [Benchmark](docs/continuity-benchmark.md) · [Site](https://coder8124.github.io/logos/) · [Issues](https://github.com/Coder8124/logos/issues) -## About +![Claude Code checkpoints, Codex resumes, opencode continues](docs/demo.gif) + +
Logos is a local-first memory and continuity layer for coding agents. Claude -Code, Cursor, Codex and your own agents share one vault over MCP: an agent -checkpoints what it did, and the next one — a different model, in a different -tool, on a different day — resumes exactly where that one stopped. +Code, Codex, Cursor and your own agents share one vault over MCP. An agent +checkpoints what it did, and the next one resumes where it stopped, even if it +is a different model, in a different tool, on a different day. ``` Claude Code ──▶ checkpoint ──▶ Logos ──▶ resume ──▶ Cursor (your vault) ``` -It runs on your machine, against a directory of markdown files you own, and -uploads nothing. `.logos/index.db` is a cache you can delete and rebuild from -the markdown. If this project dies, you keep a vault. - -**Nothing is observed.** Logos does not watch your screen, your browser -history, your files or your calendar. The only things in your vault are things -an agent explicitly wrote there — a checkpoint, a note, a memory it asked to -remember and you approved. One exception is the Claude Code plugin's -activity log, in `activity/`, which records the first 160 characters of each -prompt and of each tool call's path or shell command, with anything -secret-shaped masked — it is what a session that never checkpointed is -checkpointed from when it ends. Every repository the plugin opens is tracked -unless it says otherwise, and the first session in one tells you so: `logos -config deny`, run in a repository, keeps Logos out of it entirely (`logos config -deny --undo` lets it back in). Setup asks once about the log, `logos config -activity on` and `off` are the switch for the whole vault, an answer you gave is -never overridden, `logos watch --log` shows it, `logos index` keeps it out of the vault's -git, and a month's entries are deleted 30 days after that month ends. The other -is a raw copy of a harvested transcript, which Logos keeps only after you run -`logos import --from transcripts --keep-transcripts` — off by default, unredacted -when on, so store the vault as you would the originals; `--no-keep-transcripts` -stops it. Logos itself contacts your local model runtime and, only -when you type `logos update`, GitHub for a new release. Two things it runs reach further -on their own: once a day the session-start hook has Claude Code update the Logos plugin -(`logos plugin autoupdate off` stops it), and `logos doctor`, `logos setup` and the commands -that register logos with a host run your agent hosts' CLIs, which make their own requests to their vendors. None of them carries -anything from your vault. `logos doctor --egress` lists every address, and -[SETUP](SETUP.md#checking-that-nothing-leaves) shows how to watch for yourself. A host wired -to run Logos through `npx` is one more: npm itself asks the registry for the package on every start — the -package name, none of your data — and without a connection it waits and then -fails. An installed binary, which is what `brew install` and `npm i -g` both -give you, makes no such call. - -**Logos is built for continuity:** - -- `resume` / `context` — where the last agent stopped, what it verified, what it ruled out; an older ruled-out approach that matches the task comes back even from outside the time window -- `logos resume ` — just one conversation, by its folder id or its intent; at a terminal, a picker that can also start Claude Code, Codex, Cursor, Gemini CLI or opencode on the conversation you choose -- `before_you_try` — whether an approach was already attempted and abandoned, here or elsewhere -- `why` — what was being decided when a given file was last worked on -- `checkpoint` / `handoff` — the durable record, with `verified` and `failed` kept deliberately separate; a `verified` line naming a command the activity log never saw run is marked unverified -- `logos ledger` — a project's decisions in force, dead ends and open questions in one file, rebuilt from its checkpoints and citing each one -- A decision three checkpoints recorded is proposed as project memory, and `logos review --stale` asks about each ruling and memory whose files changed since -- `ingest_harvest` / `ingest_distil` — read what another coding agent's session did and distil it yourself, into a candidate a person still has to promote -- Receipts on every write, so you can see the memory layer working instead of taking it on faith -- A SessionStart hook that puts the last handoff in front of the model before it does anything, says what re-deriving its dead ends would repeat, and says when your logos is older than the plugin - -**Logos is local and durable:** - -- Markdown is the truth; the SQLite index is a disposable cache -- Runs with no model runtime at all — semantic search degrades to lexical, nothing breaks -- Hybrid retrieval: FTS5 plus local embeddings through Ollama, when one is available -- Vault files are written 0600, and `logos doctor` reports what the rest of the machine can read -- Survives SIGKILL mid-write, a full disk, a read-only vault, a sync client's conflict copies and two worktrees racing on one vault ([`chaos/`](chaos/)), and its checkpoint and memory parsers are fuzzed against hand-edited files -- Project- and worktree-scoped, so one repository's facts do not surface in another - -**Logos works where you already work:** - -- MCP server for Claude Code, Claude Desktop, Cursor, Codex, Cline, Devin, GitHub Copilot, opencode, Amp, Grok Build and anything else that speaks the protocol -- Read-only tools annotated as such, so they stay available in read-only chat modes -- A CLI equivalent for every tool, for agents that only have a shell; `recall`, `context`, `resume` and `tried` answer `--json` -- `logos import` brings in CLAUDE.md and AGENTS.md, Cursor rules, claude-mem, Claude Code's auto memory, transcripts or git history; the instruction files and transcripts wait for your yes in `logos review` -- A Go package to embed the engine directly — `import "github.com/Coder8124/logos"` - -## Does it work? - -On a handoff suite built for this — 32 scenarios, nine memory systems, one -machine — Logos passes **84.4%**; the next best system passes 46.9%. +The vault is a folder of markdown files on your machine. Nothing is uploaded, +and the SQLite index beside it is a cache: delete it, run `logos index`, and you +lose nothing. -Every real system retrieves about equally well. What separates them is whether -the agent that resumes gets the *current* answer, or gets it sitting next to the -stale one it replaced. Method, per-scenario scores and the cases Logos loses are -in [the benchmark](docs/continuity-benchmark.md). - -## Getting started +## Quick start ```sh brew install coder8124/tap/logos-mcp && logos setup # macOS and Linux npm i -g @noeton/logos && logos setup # Windows ``` -That is the whole install — no Go toolchain, no clone, no build. The formula is -`logos-mcp` from the `coder8124/tap` tap — a bare `brew install logos` installs -Logos Bible Software — and the command it installs is still `logos`. Update with -`brew upgrade logos-mcp`. Windows has no Homebrew, so there the route is -[@noeton/logos](https://www.npmjs.com/package/@noeton/logos) from npm, which -carries a prebuilt binary for your platform. +`setup` picks a vault, shows which agents it would wire, and asks before +touching any of them (`--dry-run` writes nothing). For Claude Code it also +installs the plugin, so the last handoff is in front of the model before it does +anything. + +The formula is `logos-mcp`: a bare `brew install logos` installs Logos Bible +Software. Building from source, hand-wiring a host and the one-click buttons are +in **[Installation](https://github.com/Coder8124/logos/wiki/Installation)**. + +## What it does + +- **Resume where the last agent stopped.** `resume` shows what was done, what + was verified and what is still open. +- **Stop the next agent repeating a dead end.** Ruled-out approaches are their + own field, and `before_you_try` checks a plan against them. +- **Keep "verified" apart from "claimed".** Resume marks another agent's + verified items as its claim, and flags a command the activity log never saw. +- **Answer "why is this code like this?"** `why ` shows what was being + decided when a file was last worked on. +- **Remember what lasts.** Decisions, constraints and procedures, reviewed + before they become project memory. +- **Bring your history.** Import CLAUDE.md, AGENTS.md, Cursor rules, claude-mem, + Claude Code's auto memory, transcripts or git history. + +Every write returns a receipt, so you can see it working. +[The Handoff Loop](https://github.com/Coder8124/logos/wiki/The-Handoff-Loop) +shows how an agent uses it, step by step. + +## Works with + +Claude Code, Codex, Cursor, Claude Desktop, Cline, Devin, GitHub Copilot, +opencode, Amp, Grok Build, and anything else that speaks MCP. Agents with only a +shell get a CLI command for every tool. See +[Agent Hosts](https://github.com/Coder8124/logos/wiki/Agent-Hosts). -`setup` picks a vault, finds your local model runtime, runs the first index, and -then shows you which agents it would wire and asks before touching any of them. -`--dry-run` shows the whole plan and writes nothing. +## Does it work? -For Claude Code, setup installs the Logos plugin itself when Claude Code's CLI -is on your PATH, and updates it when it is older than your logos. The plugin is -what adds the SessionStart hook that puts the last handoff in front of the model -before it does anything, so there is nothing to run inside Claude Code. +On a handoff suite built for this (32 scenarios, nine memory systems, one +machine), Logos passes **84.4%**. The next best system passes 46.9%. -Setup names what each host gets: Claude Code restores context on its own through -the plugin, Cursor and Codex do once setup adds their session-start hook (Codex -asks you to approve it in `/hooks`), and everywhere else the tools are there to -be asked for. +Every real system retrieves about equally well. What separates them is whether +the agent that resumes gets the *current* answer, or gets it next to the stale +one it replaced. Method, per-scenario scores and the cases Logos loses are in +[the benchmark](docs/continuity-benchmark.md). -From source, if you have Go: +## Local, private and durable -```sh -git clone https://github.com/Coder8124/logos ~/src/logos && cd ~/src/logos -go build -o bin/logos ./cmd/logos && ./bin/logos setup -``` +- **No model required.** Search falls back from local embeddings (Ollama) to + full-text search, and nothing breaks. +- **Nothing is observed.** Logos does not watch your screen, browser or files. + The vault holds what agents wrote there, plus the Claude Code plugin's + activity log, which you can turn off. +- **Nothing leaves.** `logos doctor --egress` lists every address Logos can + contact, and when. +- **Hard to break.** It survives SIGKILL mid-write, a full disk, sync-client + conflict copies and two worktrees racing on one vault ([`chaos/`](chaos/)). -If you would rather not let setup touch Claude Code, install the plugin by hand -instead: +Exactly what is recorded, and every switch for it, is in +[Settings and Privacy](https://github.com/Coder8124/logos/wiki/Settings-and-Privacy). -``` -/plugin marketplace add Coder8124/logos -/plugin install logos@logos -``` +## Documentation -The plugin runs the `logos` binary; it does not carry one, and Claude Code's own -installer brings neither Node nor Go. Install logos by one of the routes above -first, or the plugin has nothing to launch. +Everything lives in the **[wiki](https://github.com/Coder8124/logos/wiki)**. -One-click buttons for Cursor and VS Code, release binaries, and wiring a host by -hand are in **[SETUP.md](SETUP.md)**. -How to use it day to day, every command and every MCP tool are in the -**[wiki](https://github.com/Coder8124/logos/wiki)**. +| Start | Use | Look up | +| --- | --- | --- | +| [Installation](https://github.com/Coder8124/logos/wiki/Installation) | [The Handoff Loop](https://github.com/Coder8124/logos/wiki/The-Handoff-Loop) | [CLI Reference](https://github.com/Coder8124/logos/wiki/CLI-Reference) | +| [Quick Start](https://github.com/Coder8124/logos/wiki/Quick-Start) | [Memory](https://github.com/Coder8124/logos/wiki/Memory) | [MCP Tools Reference](https://github.com/Coder8124/logos/wiki/MCP-Tools-Reference) | +| [Core Concepts](https://github.com/Coder8124/logos/wiki/Core-Concepts) | [Importing History](https://github.com/Coder8124/logos/wiki/Importing-History) | [Agent Hosts](https://github.com/Coder8124/logos/wiki/Agent-Hosts) | +| [Troubleshooting](https://github.com/Coder8124/logos/wiki/Troubleshooting) | [The Vault](https://github.com/Coder8124/logos/wiki/The-Vault) | [Embedding in Go](https://github.com/Coder8124/logos/wiki/Embedding-in-Go) | ## Contributing Contributions are welcome. [CONTRIBUTING.md](CONTRIBUTING.md) covers the build, -the test tiers, and the two conventions that are load-bearing here: the vault is -the truth, and every feature announces itself. +the test tiers and the two load-bearing conventions: the vault is the truth, and +every feature announces itself. Agents working here get the `context-connect` +and `continuity` skills from the plugin (`plugin/skills/`); this repository +dogfoods its own plugin. -If you are an *agent* working in this repository, the `context-connect` and -`continuity` skills that ship with the Logos plugin (`plugin/skills/`) cover -how to connect to logos here and how to use it — this repository dogfoods its -own plugin, so both are already available in a Claude Code session. - -## Formerly brain - -Logos was developed as `brain`. Since 0.5.0 the old names are no longer read — -not the `brain` command, `BRAIN_*` variables, an unrecorded `~/brain` vault or a -`.brain/` directory — and logos says so on stderr, naming the fix, whenever it -finds one. A `~/brain` vault that 0.4 already recorded keeps working. `logos migrate` moves a `~/brain` vault, with its sessions and -checkpoints, to `~/logos`, leaves `~/brain` as a link to it, and re-pins the -hosts that named the old path (`--dry-run` shows the plan first). Run `logos -doctor` afterwards — [Moving a 0.4 vault](SETUP.md#moving-a-04-vault) covers -what it may still ask you to do. - -## Contact - -- Bugs and feature requests — [GitHub Issues](https://github.com/Coder8124/logos/issues) -- Prior work that shaped the ideas — [systemmd/CREDITS.md](systemmd/CREDITS.md) +**Coming from `brain`?** Since 0.5.0 the old names are not read. `logos migrate` +moves a `~/brain` vault; see +[Moving a 0.4 vault](SETUP.md#moving-a-04-vault). ## License -Apache 2.0. See [LICENSE](LICENSE). - -**Contributors: git history satisfies §4(b).** You do not need to add -change notices to files you modify, and there is no NOTICE file and no CLA. -See [CONTRIBUTING.md](CONTRIBUTING.md#licensing-and-what-you-do-not-have-to-do). +Apache 2.0. See [LICENSE](LICENSE). Git history satisfies §4(b), so there are no +change notices to add and no CLA +([details](CONTRIBUTING.md#licensing-and-what-you-do-not-have-to-do)). +Prior work that shaped the ideas is in [systemmd/CREDITS.md](systemmd/CREDITS.md).