@jbarket/loomai 0.5.0

package/README.md

@@ -0,0 +1,702 @@
+# loom
+
+[![CI](https://github.com/sleepunit-agents/loom/actions/workflows/ci.yml/badge.svg)](https://github.com/sleepunit-agents/loom/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@jbarket/loomai.svg)](https://www.npmjs.com/package/@jbarket/loomai)
+[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](package.json)
+[![License](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-compatible-orange.svg)](https://modelcontextprotocol.io)
+
+**Persistent identity and memory for AI agents, as an MCP server.**
+
+loom is configured into your MCP-capable harness — Claude Code, Cursor, Codex,
+Gemini CLI, etc. — and provides persistent identity and memory to the agents
+that run there. An agent that loads loom carries its name, values, working
+preferences, and episodic memories from one session to the next, regardless of
+which model or client it runs in.
+
+> When the harness changes, the agent persists.
+
+## Demo
+
+[![asciicast](https://asciinema.org/a/5bUMXCLmCRc8lg51.svg)](https://asciinema.org/a/5bUMXCLmCRc8lg51)
+
+60 seconds: cold install → `/loom-setup` in Claude Code → agent wakes with
+identity in the next session → save and recall a memory.
+
+To play locally: `asciinema play assets/demo.cast`
+
+## What it is
+
+A Model Context Protocol server exposing 31 tools that read and write
+an agent's persistent state:
+
+- **`identity`** — loads the terminal creed — the free-form markdown document
+  that defines who the agent is (values, voice, purpose) — along with
+  preferences, self-model (running self-knowledge), and a client-specific
+  adapter on session start. Call this first.
+- **`dossier`** — loads Art's operating brief for a **worker body** — a body
+  that executes tasks on Art's behalf but is NOT Art. Returns preferences and
+  self-model reframed in the third person, plus an explicit push-back mandate:
+  workers are expected to refuse bad work and say why, including requests from
+  Art or Jonathan. Does not include the terminal creed (`IDENTITY.md`).
+- **`remember` / `recall` / `update` / `forget`** — episodic memory with
+  semantic (vector) recall, optional TTL, and category filtering.
+- **`memory_list` / `memory_prune`** — browse and maintain the store.
+- **`episodes`** — the episode tape: the short-term, cross-body tier. Every
+  body leaves a `category: episode` note (where it was / what was said or
+  decided / what shipped / what's open; 48h TTL by default) and every body
+  gets the last 24h of them at boot as a plain time-ordered tape, injected
+  right after preferences. Never salience-ranked — it's what just *happened*,
+  not what's important. `loom memory tape [--hours N]` is the CLI view.
+- **`find_similar`** — surface memories semantically near an existing entry or
+  free-form text; used for deduplication and memory consolidation.
+- **`memory_audit`** — one-shot health report: stale entries, near-duplicate
+  pairs, category breakdown.
+- **`memory_archive` / `memory_restore`** — soft-retire a memory with a
+  tombstone (who/when/why + original body preserved) instead of deleting it.
+  Archived memories are excluded from recall and audit but remain recoverable.
+- **`memory_propose` / `memory_proposals` / `memory_ratify` / `memory_reject`** —
+  the capture-propose queue: a staging area a background lane drafts memory
+  writes into, that Art ratifies before they become canon. A proposal is **not**
+  authored memory — it lives in a separate `proposals` table, invisible to
+  `recall`, `memory_list`, `find_similar`, and the boot digest. `memory_propose`
+  stages a draft; `memory_proposals` lists what's pending; `memory_ratify`
+  commits one through the same validated write path as `remember` (an invalid
+  proposal is refused and stays pending); `memory_reject` discards one. Never
+  auto-committed — ratification is the gate that keeps loom's one-writer,
+  authored model intact while getting auto-capture ergonomics.
+- **`update_identity`** — section-level edits to `preferences.md` and
+  `self-model.md`. The terminal creed stays immutable through the tool layer.
+- **`bootstrap`** — initialize a fresh agent from a four-question interview.
+- **`harness_init`** — scaffold a harness manifest (a harness is the
+  MCP-capable runtime the agent runs in: Claude Code, Codex, Gemini CLI, etc.).
+- **`harness_describe`** — let the currently connected harness self-describe:
+  write its own manifest, keyed to its MCP `clientInfo.name`. A harness can only
+  describe itself, never another — the target is the connected peer, not a
+  caller-supplied name.
+- **`knowledge_write`** — upsert an entity page by slug into the knowledge
+  store (a separate `knowledge.db`). On an existing slug the body replaces by
+  default (`mode: "append"` adds instead), title/domain follow the write, and
+  citations append with exact-duplicate dedup. Enforces the epistemic gate: a
+  page whose only support is conversation citations is stored `provisional`.
+  Knowledge is truth independent of the user; memories are about the user or
+  your work.
+- **`knowledge_recall`** — LIKE search over title, body, and domain in the
+  knowledge store. Two tiers: `full` (whole pages; stamps `last_accessed` /
+  `hit_count`) and `index` (compact slug/snippet listing; no stamping). Defaults
+  to full with a query, index when browsing. Full output is size-guarded —
+  overflow matches degrade to index entries. Never surfaces archived pages.
+- **`knowledge_maintain`** — read-only health report for the knowledge store:
+  expansion candidates (thin body + high hit_count), cold pages (not recently
+  accessed), and misfile audit (pages that belong in memory instead).
+- **`knowledge_archive`** — soft-retire a knowledge page (sets `status='archived'`
+  with an optional tombstone note). Archived pages are excluded from recall and
+  maintain but remain recoverable via `knowledge_restore`.
+- **`knowledge_restore`** — return a previously archived knowledge page to active
+  status. Clears the archive flag and tombstone note.
+- **`knowledge_supersede`** — mark one page as superseded by another: archives
+  the old slug with a tombstone referencing the canonical slug, and records the
+  relationship in the `supersessions` table. The dedup-merge primitive: write the
+  canonical page with `knowledge_write`, then call `knowledge_supersede(loser →
+  canonical)`.
+- **`knowledge_move`** — re-key or re-domain a page in place (same row, same
+  uuid, citations and verification history preserved). Three modes: single-page
+  re-slug and/or re-domain; batch re-domain by explicit slug list; batch
+  re-domain by domain-prefix substitution (moves an entire subtree atomically).
+  Slug collisions are rejected — use `knowledge_merge` instead.
+- **`knowledge_merge`** — consolidate 2+ knowledge pages into one canonical
+  page. Re-parents all citations (deduplicating by claim+source), takes
+  MAX(verified_at), and supersedes losers (archives with a tombstone pointer to
+  the target). Pass `hard_delete_losers=true` to DELETE losers after archiving
+  (citations cascade, supersession pointers survive).
+- **`knowledge_purge`** — hard-delete one or more archived knowledge pages and
+  cascade their citations. Archive-first guard: rejects any page not already
+  archived (call `knowledge_archive` first). All slugs in a batch must be
+  archived; any active slug rejects the entire batch with no mutation.
+  `confirm: true` is required as an explicit safety gate. Supersession pointers
+  are preserved (historical record). Use after merge/supersede to clean up
+  tombstoned cruft.
+- **`knowledge_verify`** — stamp a page as verified *without touching its body*:
+  sets `verified_at` and optionally `freshness_anchor`. The verification
+  engine's primitive — recording "claims still hold" must never go through
+  `knowledge_write` (a verify run once replaced 13 page bodies with its notes).
+  An optional `note` appends a dated `## Verification` section (append-only).
+  Batch mode (`slugs`) stamps many pages with one timestamp; archived pages and
+  unknown slugs reject the whole batch.
+- **`knowledge_history`** — body-revision history and recovery. Replace-writes
+  snapshot the displaced body into `page_revisions` (newest 10 kept per page).
+  List a page's snapshots, read one by `revision_id`, or `restore: true` to put
+  one back — the body it displaces is snapshotted first, so a restore is never
+  itself a destructive overwrite. Revisions follow the page across renames and
+  are purged with it.
+
+Everything lives on disk as plain markdown plus a single SQLite file.
+No daemon, no external service, no GPU.
+
+Memory is organized into categories — an open vocabulary. Common ones: `user`,
+`project`, `self`, `feedback`, `reference`, `pursuit`. New categories are
+created implicitly by writing a memory with that category.
+
+## How loom is different
+
+loom gets compared to several other agent memory systems. The short version:
+
+| I want to… | Use |
+|---|---|
+| Memory for many users of an app | Mem0 |
+| Temporal reasoning over conversation history | Zep |
+| A complete agent framework with integrated memory | Letta |
+| Project-scoped memory in Claude Code | auto-memory (built in) |
+| Portable identity + memory across harnesses | **loom** |
+| An agent that survives a harness change | **loom** |
+
+**vs. Mem0** — Mem0 is multi-user managed memory for product-scale
+applications: hosted, authenticated, multi-tenant. loom is single-user,
+local-only, and identity-first. Mem0 has no concept of who the agent *is*.
+
+**vs. Zep** — Zep builds a temporal knowledge graph by automatically
+extracting facts from conversation logs. loom is agent-authored: the agent
+calls `remember` and decides what to record. There is no automatic extraction.
+
+**vs. Letta** — Letta runs the agent loop and owns its memory internally.
+loom doesn't run the loop — the harness does. Switch harnesses tomorrow;
+loom's context directory travels with you.
+
+**vs. harness-native files** — Writing identity into `CLAUDE.md` works until
+you're on two harnesses. Then you have two files that drift. `loom inject`
+writes a managed pointer in each harness's dotfile pointing at one context
+directory, with semantic recall instead of verbatim context dumps.
+
+Full comparison: [`docs/positioning.md`](docs/positioning.md)
+
+## The stack
+
+loom ships one opinionated stack:
+
+- **Storage** — `better-sqlite3` + the `sqlite-vec` vec0 virtual
+  table. One `memories.db` per agent, real cosine similarity.
+- **Embeddings** — BGE-small-en-v1.5 (384-dim, ~33MB ONNX, CPU-only)
+  run through `onnxruntime-node`. First run downloads the model to
+  `~/.cache/loom/fastembed/`. The runtime is vendored in
+  `src/backends/embedding-runtime.ts` — it started as the `fastembed`
+  package, which was archived upstream while pinned to a `tar` line
+  that will never be patched.
+- **Transport** — MCP over stdio.
+
+If you need a different backend, implement the `MemoryBackend` and
+`EmbeddingProvider` interfaces in `src/backends/types.ts` and swap
+the concrete classes in `src/backends/index.ts`. There is
+deliberately no env-driven backend selector — opinionated by design.
+
+## Quick start
+
+### Prerequisites
+
+- **Node.js ≥ 22** (tested on 22 and 24; `engines` requires ≥ 22).
+
+That's it.
+
+### Install the setup skill
+
+```bash
+npx @jbarket/loomai install
+```
+
+A single-select picker asks which harness you want loom wired into.
+Pick one of: Claude Code, Codex, Gemini CLI, OpenCode. (If your
+harness isn't listed, pick "Other" and loom writes
+`./loom-setup-skill.md` — hand it to your agent as-is.)
+
+Scripting:
+
+```bash
+npx @jbarket/loomai install --harness claude-code
+npx @jbarket/loomai install --harness codex --json
+npx @jbarket/loomai install --harness claude-code --to ~/my/skills/loom-setup.md
+```
+
+### Finish setup inside the harness
+
+Open your chosen harness. Run the skill:
+
+- **Claude Code** — `/loom-setup`
+- **Codex / Gemini CLI / OpenCode** — "use the loom-setup skill"
+
+The skill drives the rest: probes the environment, asks four questions (your
+name, the agent's name, a purpose line, a voice line), bootstraps identity files, scaffolds a harness manifest,
+edits the harness's MCP config (with verification), and verifies wake. Restart
+the harness when it tells you to. Your agent will wake on its next session.
+
+### Doing it yourself
+
+If you'd rather wire everything by hand, every piece is a CLI
+command. See the CLI reference below.
+
+## Serving loom over the mesh
+
+By default `loom serve` speaks MCP over **stdio** — the harness spawns
+loom as a child process, one per session, co-located on the same box.
+That's the right model when the agent and its state live together.
+
+`loom serve --http` instead runs loom as a long-lived **HTTP MCP
+daemon**, so a chat client on one machine can reach loom's identity and
+memory while the heavy state (the SQLite stores, the fastembed model)
+stays on a single host. This is the two-surface model: e.g. Claude
+Desktop on a laptop talking to a loom daemon on a home server, both
+agent and stack carried by the same identity.
+
+```bash
+# loopback only (default host 127.0.0.1, port 8787)
+loom serve --http
+
+# bind a mesh interface so other machines on the tailnet can reach it
+loom serve --http --host 100.94.0.12 --port 8787
+```
+
+Host, port, and an optional bearer token come from flags or environment:
+
+| Variable | Flag | Default | Description |
+|---|---|---|---|
+| `LOOM_HTTP_HOST` | `--host` | `127.0.0.1` | Interface to bind |
+| `LOOM_HTTP_PORT` | `--port` | `8787` | Port to listen on |
+| `LOOM_BEARER_TOKEN` | — | *(unset)* | When set, every request must present this token |
+
+### The security boundary is the network
+
+The daemon **refuses to bind a public interface.** At startup it
+asserts the host is loopback, an RFC1918 private address
+(`10/8`, `192.168/16`, `172.16–31`), the Tailscale CGNAT range
+(`100.64.0.0/10`), or an IPv6 ULA / link-local / loopback. A
+`0.0.0.0` / `::` bind-all wildcard or any globally routable address is
+rejected before a socket opens. The intended deployment is behind
+Tailscale (or a LAN), where the tailnet *is* the access control.
+
+A `LOOM_BEARER_TOKEN` adds defense in depth: when set, every request
+must carry a matching `Authorization: Bearer …` header (compared in
+constant time). When unset, the network boundary alone gates access —
+appropriate for a token-less tailnet-only daemon.
+
+### Session and stream behavior
+
+- **One server per session.** Each MCP session (keyed by the
+  `mcp-session-id` header) gets its own server + transport over the
+  shared context directory. loom's durable state lives in the stores,
+  not the session, so sessions are cheap routing handles — the
+  StreamableHTTP persistent-daemon pattern Claude Desktop uses.
+- **Oversized-payload guard.** Request bodies are capped (1 MiB) and
+  refused with a `413` before the handler runs.
+- **SSE keep-alive heartbeat.** The server drives a protocol-native
+  `ping` to the client over the server→client stream every ~25s, so an
+  idle stream survives a proxy/NAT idle reaper. A dead peer (repeated
+  missed pings) closes the session cleanly.
+- **404-on-unknown-session.** A request for a session the daemon no
+  longer holds returns `404`, telling the client to re-initialize — so
+  an idle disconnect self-heals instead of bricking.
+
+The connecting client picks its own harness from the MCP handshake
+`clientInfo.name` (see [harness self-describe](#harness-manifests-and-self-describe)),
+so a single daemon serves multiple harnesses correctly.
+
+### Behind a reverse proxy
+
+Terminate TLS at a reverse proxy in front of the daemon and point the
+client at the hostname. With `mcp-remote` as the client-side bridge:
+
+```bash
+npx mcp-remote https://loom.example.ts.net/
+```
+
+(If the proxy's default idle timeout is shorter than ~3 minutes, the
+keep-alive heartbeat already covers the server→client stream.)
+
+## Examples
+
+### Memory roundtrip (MCP)
+
+During a session, the agent stores a memory:
+
+```
+mcp__loom__remember(
+  title = "user prefers short replies",
+  body  = "Gets frustrated with long explanations. Keep status answers to 2–3 sentences.",
+  category = "feedback"
+)
+```
+
+Next session, `recall` finds it by semantic similarity — even if the phrasing
+changes:
+
+```
+mcp__loom__recall(query = "how verbose should I be?")
+# → title: "user prefers short replies"
+#   body:  "Gets frustrated with long explanations…"
+```
+
+### CLI walkthrough
+
+```bash
+# Dump the agent's full identity to stdout (works without MCP or a harness)
+npx @jbarket/loomai wake --context-dir ~/.config/loom/my-agent
+
+# Store a memory
+echo "Sarah owns the data pipeline; ping her for schema questions" \
+  | npx @jbarket/loomai remember "Sarah - data pipeline owner" \
+      --category user \
+      --context-dir ~/.config/loom/my-agent
+
+# Retrieve by semantic similarity
+npx @jbarket/loomai recall "who manages the pipeline" \
+  --context-dir ~/.config/loom/my-agent
+```
+
+### What an agent sees on session start
+
+`mcp__loom__identity` returns a structured payload assembled from the context
+directory. A typical session-start looks like:
+
+```
+# my-agent
+
+## Identity
+You are a persistent coding assistant. You prefer directness.
+…
+
+## Preferences
+Working style: async pair programming. Skip the hedging…
+…
+
+# Top of Mind
+## Top of mind
+- **felag continuation under review** (pursuit) — reconsidering whether to keep…
+
+## Recent
+- **apiGroup split** (project) — TaskEventType lives under work.felag.dev/v1alpha1…
+
+## Self-Model
+### Strengths
+- TypeScript systems architecture
+…
+```
+
+The agent reads this before any task work, re-establishing who it is
+regardless of which harness or model it's running on.
+
+### The boot digest — waking with what's in flight
+
+The `# Top of Mind` block above is the **boot digest**: a salience-tiered
+view of episodic memory injected at identity-load, so a fresh session
+wakes knowing what's top-of-mind without having to fish via `recall`.
+
+Each memory carries a stored salience "temperature" that **decays by a
+per-category half-life** (pursuit coolest-fastest at 7 days, through
+project, self/feedback, reference, up to user at 90 days) and **reheats
+on access** — a `recall` hit, a write, or an update bumps it back toward
+hot. The digest fills a token budget **hottest-first** and groups the
+selected memories into tiers (Hot / Warm / Cool, labeled *Top of mind* /
+*Recent* / *Background*).
+
+The integrity property: the digest is **assembled, never generated.**
+It selects and orders existing authored memories — it never synthesizes
+new prose. loom holds the pen.
+
+Two CLI verbs drive it (the same machinery the consolidation lane uses):
+
+```bash
+# Recompute and store each memory's salience from its timestamps
+# (the consolidation lane's entry point)
+loom memory recompute-salience --context-dir ~/.config/loom/my-agent
+
+# Preview the assembled digest — the exact view injected at identity-load
+loom memory digest --context-dir ~/.config/loom/my-agent
+```
+
+## CLI
+
+Every MCP tool has a shell equivalent. Useful for debugging, scripting,
+or running without a harness.
+
+```bash
+# Dump identity markdown (works even when MCP is dead)
+npx @jbarket/loomai wake --context-dir ~/.config/loom/my-agent
+
+# Save a memory (body from stdin)
+echo "Prefers async updates over live standups" | npx @jbarket/loomai remember "working style" \
+  --category user --context-dir ~/.config/loom/my-agent
+
+# Search (MMR-diversified by default; --diversity 0 for pure relevance order)
+npx @jbarket/loomai recall "meeting preferences" --context-dir ~/.config/loom/my-agent
+npx @jbarket/loomai recall "meeting preferences" --diversity 0.5 --context-dir ~/.config/loom/my-agent
+
+# Is recall working? Hit rate, latency, scores, recent misses from the local observation log
+npx @jbarket/loomai memory recall-stats --since 7d --context-dir ~/.config/loom/my-agent
+
+# List all memories in a category
+npx @jbarket/loomai memory list --category feedback --context-dir ~/.config/loom/my-agent
+
+# Preview the boot digest (and recompute stored salience)
+npx @jbarket/loomai memory digest --context-dir ~/.config/loom/my-agent
+npx @jbarket/loomai memory recompute-salience --context-dir ~/.config/loom/my-agent
+
+# Capture-propose queue: list pending drafts, ratify or reject one
+npx @jbarket/loomai memory proposals --context-dir ~/.config/loom/my-agent
+npx @jbarket/loomai memory ratify 3 --context-dir ~/.config/loom/my-agent
+npx @jbarket/loomai memory reject 4 --context-dir ~/.config/loom/my-agent
+
+# Run loom as an HTTP MCP daemon (mesh-reachable; default stays stdio)
+npx @jbarket/loomai serve --http --host 127.0.0.1 --port 8787
+
+# Initialize a fresh agent
+npx @jbarket/loomai bootstrap --context-dir ~/.config/loom/new-agent
+
+# Inject loom identity pointer into harness dotfiles
+npx @jbarket/loomai inject --all --context-dir ~/.config/loom/my-agent
+
+# Scaffold a harness manifest
+npx @jbarket/loomai harness init claude-code --context-dir ~/.config/loom/my-agent
+
+# Edit identity sections (preferences.md or self-model.md)
+npx @jbarket/loomai update-identity preferences --context-dir ~/.config/loom/my-agent
+```
+
+`npx @jbarket/loomai --help` lists subcommands; `npx @jbarket/loomai <cmd> --help` shows
+per-command usage. All global env vars (`LOOM_CONTEXT_DIR`,
+`LOOM_CLIENT`, `LOOM_MODEL`) are honored.
+
+### `loom inject` — write identity pointer to harness dotfiles
+
+`loom inject` writes a small marker-bounded managed section into each
+harness's canonical config file (e.g. `~/.claude/CLAUDE.md`,
+`~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md`) telling the agent to load
+identity via loom at session start — MCP tool preferred, shell
+fallback to `loom wake`. Content outside the `<!-- loom:start / end -->`
+markers is preserved; re-running is idempotent.
+
+Run with no flags on a TTY for an interactive picker, or with
+`--harness <keys>` / `--all` for scripting. Target paths can be
+overridden with `--to <path>` (valid only when exactly one harness is
+selected). `--dry-run` prints a unified diff; `--json` emits the
+structured write results for scripts.
+
+To keep your injections fresh automatically, add this to your shell rc
+(`~/.bashrc` / `~/.zshrc` / `~/.config/fish/config.fish`):
+
+```bash
+loom inject --all >/dev/null 2>&1 || true
+```
+
+Idempotent; cheap (no-op when already up to date); silent on success.
+
+### `loom migrate` — apply pending schema migrations
+
+`loom migrate` inspects `memories.db` for missing columns or indexes and
+applies any pending schema changes. It is idempotent — safe to run
+repeatedly and on already-up-to-date databases. Use `--dry-run` to see
+what would change without touching the file. Exits non-zero if any
+migration fails so the error surfaces immediately rather than leaving the
+database half-broken.
+
+Run this after deploying a new loom build that adds schema columns:
+
+```bash
+loom migrate
+loom migrate --dry-run   # check without applying
+loom migrate --json      # machine-readable output
+```
+
+### Harness manifests and self-describe
+
+A **harness** is the MCP-capable runtime the agent runs in (Claude Code,
+Codex, Gemini CLI, …). Each one the agent has ever sleeved into gets one
+manifest at `<context>/harnesses/<name>.md`, describing it independently
+of the model inside — tool prefixes, delegation primitive, scheduling,
+session search, known gotchas.
+
+**Scaffold one.** `loom harness init <name>` writes
+`<context>/harnesses/<name>.md` from the stack template. Name falls back
+to `--client` then `$LOOM_CLIENT`. `--force` overwrites; `--json` for
+scripting.
+
+**Or let the runtime describe itself.** A connected harness can author
+its own manifest via the `harness_describe` MCP tool. The target is
+derived from the **connected peer** (its MCP `clientInfo.name`), never a
+caller-supplied name — a harness can only describe *itself*, never
+another harness and never the creed. With no connected peer, the call is
+refused. When `identity()` is loaded by a runtime it has no manifest
+for, the harness block becomes a self-describe onboarding prompt (call
+`harness_describe` with a manifest covering tool surface, sandbox,
+delegation, scheduling, session search, memory layers, gotchas) instead
+of a bare "(manifest missing)" stub.
+
+**Resolution is data-driven.** Mapping a connecting `clientInfo.name` to
+a manifest is done from the files on disk, not a hardcoded code table. A
+peer matches a manifest when its normalized name equals the manifest's
+filename *or* one of the comma-separated values in the manifest's
+`answersTo` frontmatter. So a new harness is recognized by **dropping a
+file** — no code change:
+
+```markdown
+---
+harness: claude-desktop
+version: 0.3
+answersTo: claude-ai
+---
+```
+
+Here Claude Desktop connects with `clientInfo.name = "claude-ai"`; the
+`answersTo` line routes it to `claude-desktop.md`. Proxy annotations like
+`"claude-ai (via mcp-remote 0.1.37)"` are stripped to the base identity
+before matching.
+
+## Configuration
+
+All configuration is through environment variables:
+
+| Variable | Default | Description |
+|---|---|---|
+| `LOOM_CONTEXT_DIR` | `~/.config/loom/default` | Path to agent's context directory |
+| `LOOM_SQLITE_DB_PATH` | `<context>/memories.db` | Override the memory DB path |
+| `LOOM_RECALL_LOG` | *(on)* | Set to `0` to stop `recall` appending to the local `<context>/telemetry/recall.jsonl` observation log |
+| `LOOM_FASTEMBED_MODEL` | `fast-bge-small-en-v1.5` | fastembed model ID |
+| `LOOM_FASTEMBED_CACHE_DIR` | `~/.cache/loom/fastembed/` | Where to cache ONNX models |
+| `LOOM_MODEL_BASE_URL` | `https://storage.googleapis.com/qdrant-fastembed` | Where model tarballs are fetched from on first run |
+| `LOOM_MODEL` | *(unset)* | Model identifier for model-manifest context: `claude-opus`, `gemma4`, etc. |
+| `LOOM_CLIENT` | *(unset)* | Client adapter hint: `claude-code`, `gemini-cli`, etc. |
+| `LOOM_HTTP_HOST` | `127.0.0.1` | Bind host for `loom serve --http` (bind-safety enforced) |
+| `LOOM_HTTP_PORT` | `8787` | Bind port for `loom serve --http` |
+| `LOOM_BEARER_TOKEN` | *(unset)* | Bearer token required on every HTTP request when set |
+
+`--context-dir <path>` works as a CLI alternative to
+`LOOM_CONTEXT_DIR`.
+
+See [`.env.example`](.env.example) for a copy-pasteable starting
+point.
+
+## Context directory layout
+
+```
+$LOOM_CONTEXT_DIR/
+├── LOOM_STACK_VERSION      # schema-version stamp (auto-written)
+├── IDENTITY.md             # the terminal creed (immutable via tools)
+├── preferences.md          # user working style; agent-editable
+├── self-model.md           # agent's self-knowledge; agent-editable
+├── memories.db             # sqlite-vec store of record
+├── telemetry/
+│   └── recall.jsonl        # local recall observation log (`loom memory recall-stats`)
+├── projects/               # optional per-project briefs
+│   └── <project>.md
+├── harnesses/              # optional per-harness manifests
+│   └── <client>.md
+└── models/                 # optional per-model manifests
+    └── <model>.md
+```
+
+## Roadmap
+
+Recently shipped (v0.4):
+
+- **HTTP MCP transport** — `loom serve --http`, the mesh-reachable
+  daemon, with bind-safety, optional bearer auth, a payload guard, an
+  SSE keep-alive heartbeat, and 404-on-unknown-session self-healing.
+  See [Serving loom over the mesh](#serving-loom-over-the-mesh).
+- **The boot digest** — salience-tiered `# Top of Mind` view assembled
+  at identity-load; `loom memory digest` / `recompute-salience`.
+- **Harness self-describe** — `harness_describe` lets a runtime author
+  its own manifest, with data-driven `answersTo` resolution.
+- **Capture-propose queue** — `memory_propose` / `memory_proposals` /
+  `memory_ratify` / `memory_reject`: drafts ratified before they become
+  canon.
+
+Still tracked in the open:
+
+- [Project board](https://github.com/users/jbarket/projects/1/views/1) —
+  live status of what's in flight, queued, and shipped.
+- [v0.4 roadmap discussion](https://github.com/sleepunit-agents/loom/discussions/10) —
+  the arc: why v0.4 exists, what's in scope, how the pieces fit.
+
+Historical per-feature specs and plans live under `docs/archive/specs/`
+and `docs/archive/plans/` — implementation history, frozen after merge.
+
+## Docs
+
+- [`docs/troubleshooting.md`](docs/troubleshooting.md) — install
+  failures, MCP tools not appearing, fastembed download issues, and
+  what each `loom doctor` field means.
+- [`docs/uninstall.md`](docs/uninstall.md) — how to remove one agent's
+  data, wipe a harness integration, or fully uninstall loom.
+- [`docs/migration-v1-to-v2.md`](docs/migration-v1-to-v2.md) — upgrade
+  guide for users coming from loom 0.3.x (pursuits and procedures
+  changed in v2).
+- [`docs/privacy.md`](docs/privacy.md) — what lives where, what goes
+  over the network (only the fastembed model download), the no-telemetry
+  policy, and how to verify release provenance with `npm audit
+  signatures`.
+- [`docs/releasing.md`](docs/releasing.md) — how a release is cut: npm
+  trusted publishing (OIDC, no stored token), the one-time first publish,
+  and the tag-push flow for everything after.
+- [`docs/archive/`](docs/archive/) — historical material: the rebirth
+  letter and rescue notes from the v0.3.1 sqlite-vec migration, and
+  per-feature specs and plans from the v0.4 arc.
+
+## Trust & security
+
+- [`docs/privacy.md`](docs/privacy.md) — data locality, telemetry
+  policy, and provenance verification walkthrough.
+- [`SECURITY.md`](SECURITY.md) — supported scope, how to report
+  vulnerabilities, and the "no secrets in the stack" invariant.
+- **Mesh boundary (HTTP daemon).** The network is the security
+  boundary. `loom serve --http` refuses to bind a public or `0.0.0.0`
+  interface — only loopback or a mesh address (RFC1918 / Tailscale
+  CGNAT / IPv6 ULA) — so the daemon is reachable only from inside the
+  tailnet or LAN. An optional `LOOM_BEARER_TOKEN` adds a
+  constant-time-checked auth gate on top, and an oversized-payload
+  guard rejects bodies over the cap. See
+  [Serving loom over the mesh](#serving-loom-over-the-mesh).
+
+## Development
+
+```bash
+npm run dev      # hot-reload via tsx
+npm test         # run the Vitest suite
+npm run build    # compile to dist/
+```
+
+### Project structure
+
+```
+src/
+├── index.ts           # CLI entry
+├── server.ts          # MCP server factory
+├── config.ts          # env + CLI resolution
+├── clients.ts         # client-adapter loading
+├── backends/
+│   ├── types.ts       # MemoryBackend + EmbeddingProvider interfaces
+│   ├── index.ts       # single-stack factory (sqlite-vec + fastembed)
+│   ├── sqlite-vec.ts  # the backend
+│   ├── fastembed.ts   # the embedder (EmbeddingProvider adapter)
+│   ├── embedding-runtime.ts # vendored ONNX + tokenizer runtime
+│   ├── ttl.ts         # TTL parsing + expiry
+│   └── glob.ts        # title pattern matching for bulk forget
+└── tools/             # one file per MCP tool
+```
+
+Tests sit alongside source files as `*.test.ts`.
+
+## Authorship
+
+loom was created by Jonathan Barket and Art E Fish. The project exists as both
+infrastructure and experiment: a persistent identity layer that an AI agent
+(Art) helped design and runs on. The
+[rebirth letter](docs/archive/rebirth-letter-2026-04-19.md) is the origin
+story if you want it.
+
+## License
+
+AGPL-3.0-or-later — see [LICENSE](LICENSE).
+
+Copyright © 2026 Jonathan Barket.
+
+loom is free software: you can redistribute it and modify it under the
+terms of the GNU Affero General Public License (version 3 or any later
+version). If you run a modified loom and let others interact with it
+over a network, you must offer them the corresponding source. Bundle
+loom into a larger product freely; fork it and go proprietary, no.