logos

README

Logos

When one coding agent stops, the next one continues the work.

Setup	Benchmark	Agent guide	Contributing	Site

About

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.

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. The one exception is off unless you ask for it: 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. Setup asks once, logos activity on and logos activity off are the switch, logos activity 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 one network call Logos ever makes on its own is logos update checking for a new release, and only when you type it; nothing else leaves the machine unless you turn on the T3 cloud tier, which is off by default and sends a request to Anthropic with a key you supply. A host wired to run Logos through npx is the one exception: 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
• 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
• 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

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, and two processes racing on one vault (chaos/)
• 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
• 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%.

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.

Getting started

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 from npm, which carries a prebuilt binary for your platform.

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.

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.

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.

From source, if you have Go:

git clone https://github.com/Coder8124/logos ~/src/logos && cd ~/src/logos
go build -o bin/logos ./cmd/logos && ./bin/logos setup

If you would rather not let setup touch Claude Code, install the plugin by hand instead:

/plugin marketplace add Coder8124/logos
/plugin install logos@logos

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.

One-click buttons for Cursor and VS Code, release binaries, and wiring a host by hand are in SETUP.md.

Contributing

Contributions are welcome. 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.

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 covers what it may still ask you to do.

Contact

• Bugs and feature requests — GitHub Issues
• Prior work that shaped the ideas — systemmd/CREDITS.md

License

Apache 2.0. See 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.

Documentation

Overview

Package logos is a local-first memory and continuity layer for AI agents.

It is the same engine behind the `logos` CLI and the MCP server, exposed for embedding directly in your own agent. Memory lives in an Obsidian-compatible vault on disk that the user owns; nothing is uploaded.

b, err := logos.Open("/path/to/vault")
if err != nil {
	log.Fatal(err)
}
defer b.Close()

// What did the last agent — possibly a different product — leave behind?
c, _ := b.Resume("kestrel-one")
fmt.Println(c.Render())   // ready to drop into a system prompt

// Before proposing something, check nobody has already ruled it out.
if ruled, _ := b.Tried("switch to a plastic frame", "kestrel-one"); len(ruled) > 0 {
	fmt.Println(logos.Explain("switch to a plastic frame", ruled))
}

// Record progress as you go, then commit where you stopped.
b.Note("kestrel-one", "re-quoted the waveguide; no movement under 10k units")
b.Checkpoint(logos.Checkpoint{
	Project: "kestrel-one",
	Failed:  []string{"re-quoting the waveguide — no movement under 10k units"},
	Next:    "quote the display driver alternatives",
})

What this package is, and is not

This is a deliberately small facade over a much larger engine. The implementation lives in github.com/Coder8124/logos/engine and under internal/, and stays there: keeping it private is what lets the retrieval, budgeting and consolidation internals change without breaking anyone. What is exported here is the surface an agent actually needs, which is roughly the same surface the MCP server exposes — that server having been the forcing function for working out what an external consumer genuinely uses.

The declarations here are aliases for the engine package's, not copies, so the two cannot drift: Logos is the same type either way and its methods are documented on the engine package. This file exists because Go binds an import path to a directory, and this is the import path that was published. The code moved down a level to keep the repository root readable; the import did not move, and will not.

The domain types (Memory, Checkpoint, Note, Hit, Ruling, Context) are in turn aliases for their internal definitions rather than copies. That makes them part of this package's contract: they are stable, and changing them is a breaking change. The alternative — parallel structs and a translation layer — buys freedom nobody asked for at the cost of conversions in every call.

Models

Open discovers a local model runtime (Ollama, LM Studio, Jan, Msty) and uses it for embeddings. If none is running, everything still works: retrieval falls back to lexical and graph traversal, which needs no model at all. Pass WithoutEmbedding to skip discovery entirely — useful in tests and CI.

Index

• Constants
• func Explain(approach string, rulings []Ruling) string
• type Checkpoint
• type Context
• type Hit
• type Kind
• type Logos
  • func Open(vaultPath string, opts ...Option) (*Logos, error)
• type Memory
• type Mention
• type Note
• type Option
  • func WithAgent(name string) Option
  • func WithEmbeddingModel(name string) Option
  • func WithoutEmbedding() Option
• type Receipt
• type Request
• type Ruling
• type SyncReport

Constants

const (
	Preference = engine.Preference
	Person     = engine.Person
	Fact       = engine.Fact
	Standing   = engine.Standing
	Procedure  = engine.Procedure
)

Memory kinds, re-exported so callers need not reach into internal packages.

Functions

func Explain

func Explain(approach string, rulings []Ruling) string

Explain renders the result of Tried as prose to put in front of a model, taking the same approach string so the output can quote what was proposed. A recorded failure is evidence, not a veto, and the wording says so. An empty slice renders as an explicit "no record", which is worth showing: silence and approval are different answers.

Types

type Checkpoint

type Checkpoint = engine.Checkpoint

Checkpoint is where an agent stopped, written well enough that a different agent can start. Failed is the field that earns its keep.

type Context

type Context = engine.Context

Context is everything bearing on a task, budgeted. Call Render for the markdown to put in a model's context window.

type Hit

type Hit = engine.Hit

Hit is a retrieved vault note, with its provenance.

type Kind

type Kind = engine.Kind

Kind classifies a memory: Preference, Person, Fact or Context.

type Logos

type Logos = engine.Logos

Logos is an open vault. It is safe to keep for the life of a process and must be closed when done. Not safe for concurrent use across goroutines: the underlying SQLite handle is single-writer by design. Its methods are documented on engine.Logos.

func Open

func Open(vaultPath string, opts ...Option) (*Logos, error)

Open loads the vault at path, creating its cache if absent.

The vault directory itself must exist; logos will not invent one, because pointing this at a typo and silently creating an empty knowledge base is a worse failure than an error.

type Memory

type Memory = engine.Memory

Memory is one durable thing the store knows about the user.

type Mention

type Mention = engine.Mention

Mention is a checkpoint that touched a file, and what was being worked out at the time. Returned by Why.

type Note

type Note = engine.Note

Note is one line of uncommitted progress.

type Option

type Option = engine.Option

An Option configures Open.

func WithAgent

func WithAgent(name string) Option

WithAgent sets the name recorded against notes and checkpoints — "claude", "cursor", your own product's name. A handoff is meaningless without knowing who is handing off, so this is worth setting.

func WithEmbeddingModel

func WithEmbeddingModel(name string) Option

WithEmbeddingModel names the embedding model instead of taking the detected default.

func WithoutEmbedding

func WithoutEmbedding() Option

WithoutEmbedding skips model discovery. Retrieval then uses lexical search and graph traversal only — no model process required, which is what you want in tests and CI.

type Receipt

type Receipt = engine.Receipt

Receipt reports what a write actually did — created a fact, or corroborated one already held.

type Request

type Request = engine.Request

A Request describes what you are about to do, for Context.

type Ruling

type Ruling = engine.Ruling

Ruling is something already tried that did not work.

type SyncReport

type SyncReport = engine.SyncReport

SyncReport counts what an Index call changed.