How Seamless works

One daemon, three surfaces, and a hard line between the files that are truth and the database that is an index.

Seamless is a local-first memory and coordination system for coding agents. The release ships a daemon (seamlessd) and its headless client (seam); one daemon process owns one SQLite database and one directory of markdown files, bound to loopback on your machine. Agents reach it over MCP, hooks make sessions ambient for Claude Code and Codex, and you watch through a read-mostly console. It is deliberately not a distributed system - one instance, one port, one data directory per machine. Everything below follows from that.

One daemon, three surfaces

Local architecture

MCPAgentsTools and session binding

Command → HTTPHooksAmbient context and harvest

BrowserYouRead-mostly console

seamlessdone local process · 127.0.0.1:8081

Durable truthmemory/*.md

Durable truthnotes/*.md

State + indexesseam.db

One daemon, three interfaces. Agents and hooks write through the same process; humans inspect the resulting state in the console.

Agents speak MCP at /api/mcp. This is the primary interface; the clients of Seamless are programs, not people.
Hooks are how sessions become ambient. Claude Code calls them at session start, on each prompt, and at session end, so an agent gets briefed and harvested without ever choosing to.
You get a read-mostly console. It is an observability surface, not the way the system is driven.

One instance per machine, one port, one data directory. Not a distributed system, by choice.

Files are truth; the database is an index

This is the load-bearing decision in the whole design.

	Lives in	Why
Memories, notes	Markdown files	Durable knowledge you own: readable, greppable, editable, git-able
Sessions, tasks, trials, events, telemetry	SQLite	High-churn state with no reason to be a file
FTS index, embeddings	SQLite	Derived data, rebuildable from the files

So: what would you lose if seam.db were deleted? The sessions, the task queue, the trials, and the event log - the record of what happened. You would not lose a single memory or note, because those are files, and startup reconciliation rebuilds their index from the disk.

That asymmetry is the point. The knowledge is yours in the strongest sense: it survives this program. If Seamless disappeared tomorrow, you would still have a folder of markdown files that a human - or any other tool - can read.

The write path

Write path

1 · requestmemory_writeValidate name, content, and scope

2 · durable actAtomic Markdown writeFail closed when scope is ambiguous

3 · rebuildableFTS + embeddingIndex the exact file content

4 · observableAppend eventRecord what happened

The file is the durable boundary. SQLite mirrors make the knowledge searchable and observable.

The file write is the one that matters. Indexing after it can fail and be rebuilt; the file is already on disk.

The read path

Three retrieval paths

SessionStartcwd → project → budgeted briefing → injectBaseline context before the first action

UserPromptSubmitprompt match → <seam-recall> → injectFocused context for the current request

recallFTS5 + cosine → RRF fusion → budget → returnExplicit search initiated by the agent

Automatic briefing, prompt-matched injection, and explicit recall share the same knowledge but answer different moments in an agent run.

All three are covered in Recall and Sessions & briefings.

What Seamless is not

Not a RAG pipeline over your codebase. It stores what agents learned, not what the code says. The code is already in the repo; duplicating it into memory is how a store fills with noise.
Not a vector database. Vectors are float32 blobs in SQLite, scanned exactly. No ANN index, no separate service.
Not a cloud service. No account, no sync, and no outbound product telemetry. The local event and retrieval telemetry shown in the console never leaves the machine. The bind is loopback and the key is static.
Not autonomous. The gardener proposes; you decide. Nothing rewrites your knowledge behind your back.
Not a chat memory. It is not trying to remember your conversation. It remembers decisions, constraints, and dead ends across many agents and many months.