README
¶
Logos
When one coding agent stops, the next one continues the work.
Docs · Quick Start · Benchmark · Site · Issues
Logos is a local-first memory and continuity layer for coding agents. Claude 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)
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.
Quick start
brew install coder8124/tap/logos-mcp && logos setup # macOS and Linux
npm i -g @noeton/logos && logos setup # Windows
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.
What it does
- Resume where the last agent stopped.
resumeshows 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_trychecks 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 <path>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 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.
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 next to the stale one it replaced. Method, per-scenario scores and the cases Logos loses are in the benchmark.
Local, private and durable
- 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 --egresslists 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/).
Exactly what is recorded, and every switch for it, is in Settings and Privacy.
Documentation
Everything lives in the wiki.
| Start | Use | Look up |
|---|---|---|
| Installation | The Handoff Loop | CLI Reference |
| Quick Start | Memory | MCP Tools Reference |
| Core Concepts | Importing History | Agent Hosts |
| Troubleshooting | The Vault | Embedding in Go |
Contributing
Contributions are welcome. CONTRIBUTING.md covers the build,
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.
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.
License
Apache 2.0. See LICENSE. Git history satisfies §4(b), so there are no change notices to add and no CLA (details). Prior work that shaped the ideas is in systemmd/CREDITS.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 ¶
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.
Variables ¶
This section is empty.
Functions ¶
func Explain ¶
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 ¶
Context is everything bearing on a task, budgeted. Call Render for the markdown to put in a model's context window.
type 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.
type Mention ¶
Mention is a checkpoint that touched a file, and what was being worked out at the time. Returned by Why.
type Option ¶
An Option configures Open.
func WithAgent ¶
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 ¶
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 ¶
Receipt reports what a write actually did — created a fact, or corroborated one already held.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
logos
command
Command logos is the CLI front end.
|
Command logos is the CLI front end. |
|
Package engine is the implementation behind github.com/Coder8124/logos.
|
Package engine is the implementation behind github.com/Coder8124/logos. |
|
examples
|
|
|
handoff
command
Command handoff is the smallest useful embedding of logos: two agents, one vault, no shared process.
|
Command handoff is the smallest useful embedding of logos: two agents, one vault, no shared process. |
|
internal
|
|
|
activity
Package activity is the append-only record of what an agent actually did.
|
Package activity is the append-only record of what an agent actually did. |
|
advice
Package advice is what a checkpoint receipt says about the checkpoint it just wrote: the placeholders it dropped and the fields it kept as given but doubts.
|
Package advice is what a checkpoint receipt says about the checkpoint it just wrote: the placeholders it dropped and the fields it kept as given but doubts. |
|
agent
Package agent is the conversational assistant.
|
Package agent is the conversational assistant. |
|
agentprompt
Package agentprompt carries the instructions an agent should read before it uses Logos.
|
Package agentprompt carries the instructions an agent should read before it uses Logos. |
|
announce
Package announce decides how loudly Logos says what it just did.
|
Package announce decides how loudly Logos says what it just did. |
|
auto
Package auto is what Logos does without being asked, in one place.
|
Package auto is what Logos does without being asked, in one place. |
|
bootstrap
Package bootstrap seeds a cold vault from the git history already on disk.
|
Package bootstrap seeds a cold vault from the git history already on disk. |
|
buildinfo
Package buildinfo holds the one version string this product reports.
|
Package buildinfo holds the one version string this product reports. |
|
claims
Package claims holds a checkpoint's testimony up against what the host saw happen in the same session.
|
Package claims holds a checkpoint's testimony up against what the host saw happen in the same session. |
|
claudemem
Package claudemem finds claude-mem's local store.
|
Package claudemem finds claude-mem's local store. |
|
consent
Package consent tracks whether the app is allowed to call agent.Learn after a chat exchange without asking first.
|
Package consent tracks whether the app is allowed to call agent.Learn after a chat exchange without asking first. |
|
contextpack
Package contextpack assembles everything needed to work on something into one bundle.
|
Package contextpack assembles everything needed to work on something into one bundle. |
|
deadend
Package deadend answers one question: has this been tried before?
|
Package deadend answers one question: has this been tried before? |
|
dream
Package dream is the nightly consolidation pass — logos sleeping on the day.
|
Package dream is the nightly consolidation pass — logos sleeping on the day. |
|
flavor
Package flavor holds the assistant's identity and how present it makes itself.
|
Package flavor holds the assistant's identity and how present it makes itself. |
|
gitstate
Package gitstate reads what the repository was, so a checkpoint does not have to rely on being told.
|
Package gitstate reads what the repository was, so a checkpoint does not have to rely on being told. |
|
graph
Package graph builds the memory graph the widget renders.
|
Package graph builds the memory graph the widget renders. |
|
health
Package health answers "is this actually working", and is careful about the difference between a thing that is fine and a thing nobody looked at.
|
Package health answers "is this actually working", and is careful about the difference between a thing that is fine and a thing nobody looked at. |
|
hostdir
Package hostdir says where Claude Code and Codex keep their files.
|
Package hostdir says where Claude Code and Codex keep their files. |
|
index
Package index is the rebuildable cache.
|
Package index is the rebuildable cache. |
|
ingest
Package ingest turns another coding agent's transcript into a Logos checkpoint *candidate* — never a checkpoint, and never by replaying the transcript.
|
Package ingest turns another coding agent's transcript into a Logos checkpoint *candidate* — never a checkpoint, and never by replaying the transcript. |
|
insight
Package insight surfaces observations the vault already contains but nobody has stated out loud: a blocker that has survived several checkpoints without being resolved, a memory nobody has drawn on in months.
|
Package insight surfaces observations the vault already contains but nobody has stated out loud: a blocker that has survived several checkpoints without being resolved, a memory nobody has drawn on in months. |
|
mcpserver
Package mcpserver exposes logos's memory layer as an MCP server.
|
Package mcpserver exposes logos's memory layer as an MCP server. |
|
memory
Package memory is the assistant's persistent memory.
|
Package memory is the assistant's persistent memory. |
|
ops
Package ops is each operation once, for every surface.
|
Package ops is each operation once, for every surface. |
|
procedure
Package procedure answers the question before_you_try's dead-end half leaves unanswered: not just what was ruled out, but what is known to work, including the trap in doing it the obvious way.
|
Package procedure answers the question before_you_try's dead-end half leaves unanswered: not just what was ruled out, but what is known to work, including the trap in doing it the obvious way. |
|
project
Package project auto-detects the pieces of work a life is organised around and assembles a dossier for each — its notes, the people involved, the files it touches, its goals, and recent progress — without the user filing anything.
|
Package project auto-detects the pieces of work a life is organised around and assembles a dossier for each — its notes, the people involved, the files it touches, its goals, and recent progress — without the user filing anything. |
|
provider
Package provider is one client for every model runtime.
|
Package provider is one client for every model runtime. |
|
reflection
Package reflection is descriptive statistics over long-term memory.
|
Package reflection is descriptive statistics over long-term memory. |
|
rename
Package rename moves every trace of a project from one name to another, so that renaming a project is an ordinary edit rather than an event that costs you your history.
|
Package rename moves every trace of a project from one name to another, so that renaming a project is an ordinary edit rather than an event that costs you your history. |
|
replay
Package replay is "catch me up since I've been away."
|
Package replay is "catch me up since I've been away." |
|
router
Package router decides which model does which job.
|
Package router decides which model does which job. |
|
scope
Package scope answers one question — what is the work in this directory called — the same way for every caller, so that a hook, the CLI and the MCP server cannot disagree about it.
|
Package scope answers one question — what is the work in this directory called — the same way for every caller, so that a hook, the CLI and the MCP server cannot disagree about it. |
|
secret
Package secret masks credentials in text before it is written to the vault.
|
Package secret masks credentials in text before it is written to the vault. |
|
secretary
Package secretary tracks the open loops an agent or a person has left open — "I'll send the deck", "waiting on the vendor" — so they can be surfaced again without depending on anyone remembering to check.
|
Package secretary tracks the open loops an agent or a person has left open — "I'll send the deck", "waiting on the vendor" — so they can be surfaced again without depending on anyone remembering to check. |
|
selfupdate
Package selfupdate implements `logos update`: check GitHub for a newer release, verify it actually runs on this machine, then replace the running binary.
|
Package selfupdate implements `logos update`: check GitHub for a newer release, verify it actually runs on this machine, then replace the running binary. |
|
session
Package session records what an agent was doing, so a different agent can pick it up.
|
Package session records what an agent was doing, so a different agent can pick it up. |
|
setup
Package setup connects logos to the agents that will use it.
|
Package setup connects logos to the agents that will use it. |
|
spend
Package spend reads what coding agents on this machine spent, from the transcripts their hosts already keep: Claude Code's under ~/.claude/projects and Codex's under ~/.codex/sessions.
|
Package spend reads what coding agents on this machine spent, from the transcripts their hosts already keep: Claude Code's under ~/.claude/projects and Codex's under ~/.codex/sessions. |
|
testenv
Package testenv keeps test runs away from the developer's real host CLIs.
|
Package testenv keeps test runs away from the developer's real host CLIs. |
|
text
Package text holds the small string-shortening helpers that were copied, subtly differently, into half a dozen packages.
|
Package text holds the small string-shortening helpers that were copied, subtly differently, into half a dozen packages. |
|
textmatch
Package textmatch is the small lexical toolkit two subsystems needed at once.
|
Package textmatch is the small lexical toolkit two subsystems needed at once. |
|
transcript
Package transcript reads other coding agents' on-disk session logs and normalises them into a common shape.
|
Package transcript reads other coding agents' on-disk session logs and normalises them into a common shape. |
|
untrusted
Package untrusted renders vault content that was written by someone else's agent, not by logos itself.
|
Package untrusted renders vault content that was written by someone else's agent, not by logos itself. |
|
usage
Package usage is the ledger `logos usage` reads: what each context pack cost against what it drew from, and each time a recorded dead end was handed back to an agent about to retry it.
|
Package usage is the ledger `logos usage` reads: what each context pack cost against what it drew from, and each time a recorded dead end was handed back to an agent about to retry it. |
|
vault
Package vault reads and writes notes in the Obsidian vault.
|
Package vault reads and writes notes in the Obsidian vault. |
|
when
Package when resolves the time expressions people put in questions.
|
Package when resolves the time expressions people put in questions. |