seamless

README

Seamless

Local-first memory and coordination substrate for AI coding agents.

Seamless gives a fleet of agents (Claude Code, Codex, 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

curl -fsSL https://thereisnospoon.org/install | sh

On Windows, the same install in PowerShell:

irm https://thereisnospoon.org/install.ps1 | iex

That is the whole install. It needs curl and tar and nothing else -- no Go, no CGO toolchain, no database, no Node. It fetches the checksum-verified release archive for your platform (macOS, Linux, and Windows; amd64 and arm64), installs seamlessd and seam into ~/.local/bin, generates the bearer key, installs the Claude Code hooks, registers the MCP server, and runs the daemon as a per-user service -- launchd on macOS, systemd --user on Linux, an at-logon Scheduled Task on Windows. Re-run it to upgrade: your config and ~/.seamless are never touched.

Then just start Claude Code in a git repo. There is no project to create and no repo to register: the session-start hook resolves your cwd to its git root, derives a project from the repo's directory name, and records the mapping on the spot, so agents inherit project scope without passing it on every call. Reach for seamlessd map-repo --path ~/code/myrepo --project myrepo only to override the derived slug.

It is one shell script and piping a stranger's script into a shell deserves a read first. Prefer a toolchain, or want the pieces one at a time?

go install github.com/0spoon/seamless/cmd/...@latest   # Go 1.25+; seamlessd + seam
seamlessd serve                   # 127.0.0.1:8081; first run generates the API key
seamlessd install-hooks           # Claude Code hooks + MCP registration

install-hooks registers the MCP server with claude mcp add --scope user. For Codex CLI, seamlessd install-hooks --client codex installs its three hooks and registers the seam mcp-proxy stdio bridge; other MCP clients register http://127.0.0.1:8081/api/mcp with Authorization: Bearer <mcp.api_key>. From a clone, make build && make run is the same daemon out of ./bin/, and make install sets it up as a service.

The curl installer drops a /seam-onboard Claude Code skill into ~/.claude/skills/; run /seam-onboard once in Claude Code to write a Seamless-awareness block into a global or project CLAUDE.md, so agents know when to reach for it. From a clone, make install-onboard-skill (re)installs the same skill.

Then: Quickstart · Claude Code setup · Codex CLI 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.