README
¶
Seamless
Local-first memory and coordination substrate for AI coding agents.
Seamless gives a fleet of agents (Claude Code and any MCP-compatible client) a shared, durable memory and a way to divide work without colliding: memories with a supersession lifecycle, hybrid recall, a dependency-aware task queue with lease-based claiming, captured plans, and research trials. Durable knowledge is stored as markdown files on disk; a single Go binary indexes it, serves it over MCP, and renders a web console for inspection.
Full documentation: thereisnospoon.org/docs/
· Website: thereisnospoon.org (source in
docs/)
Design principles
- Built for a fleet, not a lone agent. Real coordination primitives: a dependency-aware ready-queue, atomic lease-based task claiming, and plans composed of notes and steps, so agents divide labor instead of colliding.
- Files are the source of truth. Every memory and note is a markdown file
with YAML frontmatter under
~/.seamless-- git-diffable, greppable, hand-editable. SQLite is a rebuildable index; delete it and lose nothing. - Curation proposes, humans dispose. The gardener's dedup, staleness, merge, and stale-plan passes only propose; applying is an explicit action. Supersession preserves provenance, so nothing is silently rewritten.
- One binary, no ceremony. Static Go binary, no CGO, pure-Go SQLite, no Node, no separate vector engine, no cloud account.
Quick start
Requires Go 1.25+. No CGO toolchain, no external database, no Node.
go install github.com/0spoon/seamless/cmd/...@latest # seamlessd + seam
seamlessd serve # 127.0.0.1:8081; first run generates the API key
seamlessd install-hooks # Claude Code hooks + MCP registration
seamlessd map-repo --path ~/code/myrepo --project myrepo
On a true first run serve writes a generated bearer key to
~/.config/seamless/seamless.yaml. install-hooks installs the Claude Code
hooks and registers the MCP server (claude mcp add --scope user); other MCP
clients register http://127.0.0.1:8081/api/mcp with
Authorization: Bearer <mcp.api_key>. map-repo binds a working directory to
a project, so agents in that repo inherit project scope without passing it on
every call. From a clone, make build && make run is the same daemon out of
./bin/, and make install sets it up as a service.
make install-onboard-skill installs a /seam-onboard Claude Code skill that
walks an agent through this setup and verifies each step.
Then: Quickstart · Claude Code setup · Install & deploy
Documentation
The full docs are at
thereisnospoon.org/docs/ (sources in
docs-src/, generated by cmd/docsgen).
| Concepts | Memory & notes, sessions & briefings, recall, tasks & plans, projects & scope, the gardener |
| Guides | Integrating an agent, writing memories that get recalled, coordinating a fleet, troubleshooting |
| Reference | Every MCP tool, both CLIs, every config key, the hooks, and the file formats |
| Internals | Architecture, contributing, domain invariants |
This README is deliberately short. Anything that can drift from the code -- tool
counts, config keys, CLI flags -- lives in the docs site, where the reference
pages are generated from the code itself and make check fails if they go stale.
Development
make build # ./bin/seamlessd + ./bin/seam
make test # unit tests
make test-race # unit tests under the race detector
make bench # hot-path benchmarks (recall, briefing, matcher, event fan-out)
make lint # golangci-lint
make check # the full gate: build + vet + fmt-check + docs-check + lint + test-race
make doctor # config + database self-checks
make run # serve on 127.0.0.1:8081
make docs # regenerate the docs site (docs-src/ -> docs/docs/, committed)
make docs-serve # regenerate + serve the site at 127.0.0.1:8899/docs/
Tests are table-driven with testify/require against fresh or in-memory SQLite.
Use make fmt rather than gofmt -w .: the Make target scopes formatting to
git-tracked files, while a bare gofmt walk also rewrites dot-directories that
Go's ./... pattern excludes.
The docs site's output under docs/docs/ is committed, and make check runs
docs-check, so a change to docs-src/ -- or to the tool surface or config keys
the reference generates from -- must be followed by make docs in the same
change. See docs/README-site.md.
Conventions live in AGENTS.md; read it before writing code.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
docsgen
command
Command docsgen renders the Seamless documentation site: markdown authored in docs-src/ becomes static HTML committed under docs/docs/, served by the same GitHub Pages config as the landing page (thereisnospoon.org/docs/).
|
Command docsgen renders the Seamless documentation site: markdown authored in docs-src/ becomes static HTML committed under docs/docs/, served by the same GitHub Pages config as the landing page (thereisnospoon.org/docs/). |
|
seam
command
Command seam is the headless Seamless CLI.
|
Command seam is the headless Seamless CLI. |
|
seamlessd
command
Command seamlessd is the Seamless server daemon and operator CLI.
|
Command seamlessd is the Seamless server daemon and operator CLI. |
|
internal
|
|
|
capture
Package capture fetches external URLs into note content behind SSRF guards.
|
Package capture fetches external URLs into note content behind SSRF guards. |
|
config
Package config loads Seamless configuration from a single YAML file with SEAMLESS_* environment overrides.
|
Package config loads Seamless configuration from a single YAML file with SEAMLESS_* environment overrides. |
|
console
Package console serves the Seamless observability UI: server-rendered html/template pages plus an SSE feed, with no node/npm/React or build step.
|
Package console serves the Seamless observability UI: server-rendered html/template pages plus an SSE feed, with no node/npm/React or build step. |
|
core
Package core holds Seamless domain types shared across packages: Project, Memory, Session, Task, Trial, Event, and their enums.
|
Package core holds Seamless domain types shared across packages: Project, Memory, Session, Task, Trial, Event, and their enums. |
|
events
Package events is the append-only event log: the single write path for the record of everything (session lifecycle, memory write/read/supersede, injection, task transition, gardener action).
|
Package events is the append-only event log: the single write path for the record of everything (session lifecycle, memory write/read/supersede, injection, task transition, gardener action). |
|
files
Package files is the markdown layer: memory and note files are the source of truth for durable knowledge.
|
Package files is the markdown layer: memory and note files are the source of truth for durable knowledge. |
|
gardener
Package gardener runs the propose-only maintenance passes over the memory corpus: it finds near-duplicate memories (dedup), memories that have gone untouched for too long (staleness), and rolls recent sessions into a monthly digest.
|
Package gardener runs the propose-only maintenance passes over the memory corpus: it finds near-duplicate memories (dedup), memories that have gone untouched for too long (staleness), and rolls recent sessions into a monthly digest. |
|
hooks
Package hooks serves the Claude Code SessionStart and UserPromptSubmit hook endpoints and installs/removes their entries in a settings.json.
|
Package hooks serves the Claude Code SessionStart and UserPromptSubmit hook endpoints and installs/removes their entries in a settings.json. |
|
importer
Package importer migrates Seam v1 data (~/.seam) into Seamless.
|
Package importer migrates Seam v1 data (~/.seam) into Seamless. |
|
lifecycle
Package lifecycle carries a memory's bi-temporal lifecycle: supersession (one memory replacing another) and provenance.
|
Package lifecycle carries a memory's bi-temporal lifecycle: supersession (one memory replacing another) and provenance. |
|
llm
Package llm provides embedding clients for the configured provider.
|
Package llm provides embedding clients for the configured provider. |
|
markdown
Package markdown renders agent-authored markdown as sanitized HTML for the Seamless console.
|
Package markdown renders agent-authored markdown as sanitized HTML for the Seamless console. |
|
mcp
Package mcp hosts the Seamless MCP tool surface over streamable HTTP with a single static bearer key.
|
Package mcp hosts the Seamless MCP tool surface over streamable HTTP with a single static bearer key. |
|
plans
Package plans holds the shared vocabulary of captured Claude Code plans: the note-slug prefixes, the plan-status tag lifecycle, and the tracking-task composition.
|
Package plans holds the shared vocabulary of captured Claude Code plans: the note-slug prefixes, the plan-status tag lifecycle, and the tracking-task composition. |
|
retrieve
Package retrieve assembles what an agent sees from its memory: the session-start briefing, the user-prompt-submit recall block, and the recall tool's fused search.
|
Package retrieve assembles what an agent sees from its memory: the session-start briefing, the user-prompt-submit recall block, and the recall tool's fused search. |
|
store
Free-text search over the structured entities -- tasks, sessions, projects, plans.
|
Free-text search over the structured entities -- tasks, sessions, projects, plans. |
|
validate
Package validate provides shared input-validation helpers enforcing the filesystem-safety invariants in AGENTS.md:
|
Package validate provides shared input-validation helpers enforcing the filesystem-safety invariants in AGENTS.md: |