seamless CLAUDE.md

CLAUDE.md

Quick-reference for AI assistants working in the Seamless repository. For coding conventions see AGENTS.md.

What is Seamless?

Seamless is a local-first agent memory and coordination substrate. Its clients are AI agents (Claude Code and friends); the human is an observer/editor. It provides persistent memory with a lifecycle (supersession, provenance, archival, a gardener), ambient sessions via Claude Code hooks, a dependency-aware task ready-queue, research trials, hybrid recall, and a read-mostly observability console. Go backend, no CGO, single binary + CLI.

It is a ground-up rebuild of Seam v1 (a private predecessor, read-only reference). As of the P6 cutover (2026-07-10) Seamless is the sole agent-memory system, serving on port 8081 with data dir ~/.seamless and env prefix SEAMLESS_*. v1 is decommissioned (launchd services disabled, port 8080 freed) with ~/.seam preserved read-only as a fallback archive.

Project structure

cmd/seamlessd/     server daemon: serve, doctor, import, install-hooks, map-repo,
                   family, console-open
cmd/seam/          headless CLI (agents + owner observability)  [P2/P5]
cmd/docsgen/       docs site generator: docs-src/ -> docs/docs/ (see SITE.md)
cmd/demoseed/      thin CLI over internal/demokit: the console-fleet seed
                   (branding screenshots) and `-scenes` (the shared fixture)
cmd/seambench/     agent-scenario benchmark: `run` (headless scenario x condition
                   matrix) + `report` (grade, uplift, version deltas). Driven by
                   `make seambench`; see cmd/seambench/README.md
docs-src/          docs site markdown + nav.yaml (source; docs/docs/ is output)
internal/core/     domain types: Project, Memory, Session, Task, Trial, Event
internal/config/   single YAML + env config (static key, budgets, briefing tunables, llm)
internal/store/    SQLite: schema, FTS5, embeddings (BLOB + cosine), migrations;
                   index_work.go mirrors the DB-native work record (tasks,
                   trials, session findings) into the same fts table the files
                   layer fills with memories and notes
internal/events/   append-only event log; SSE fan-out; retrieval stats
internal/validate/ path/title/name guards
internal/files/    markdown layer: frontmatter, atomic writes, watcher     [P1]
internal/markdown/ agent markdown -> sanitized console HTML (goldmark + bluemonday)
internal/llm/      OpenAI (default), Ollama, Anthropic chat + embeddings   [P1]
internal/retrieve/ briefing assembler, prompt-context matcher, recall (RRF),
                   console search                                          [P2/P4]
internal/lifecycle/ supersession, archival, provenance                     [P3]
# (the dependency-aware ready-queue + lease-based claiming live in
#  internal/store/tasks*.go -- there is no internal/tasks package)
internal/gardener/ the propose-only passes (dedup, staleness, stale-stage,
                   dead-weight, digest, stale-plan, memory-wanted -- the
                   canonical list is RunOnce), plus the request- and
                   split-driven proposals                                  [P4]
internal/plans/    captured CC plan vocabulary: tags, statuses, tracking task
internal/mcp/      MCP tools (streamable HTTP, static bearer key); see ToolCount [P2+]
internal/hooks/    session hooks + CC plan-mode capture (PostToolUse etc.) [P2/P3]
internal/console/  server-rendered observability UI (html/template + SSE)  [P5]
internal/capture/  SSRF-safe URL fetch                                     [P4]
internal/importer/ one-shot import of the v1 (~/.seam) snapshot
internal/demokit/  importable fixture-seeding primitives + the demo spec sets;
                   the shared seam under BOTH branding and the benchmark
internal/bench/    agent-scenario benchmark: scenario table, condition arms,
                   graders (repo assertions + event log + optional LLM judge),
                   results/uplift aggregation, the on-disk artifact contract
scripts/fixture/   the shared throwaway fixture: make-myapp.sh (demo repo) +
                   harness.sh --mode record|bench (branding | benchmark arms)
scripts/branding/  GH-Pages surface: record.sh, distill.py (verbatim-audited
                   scene data), console-shots.js -- see its README.md