loom
loom provides persistent, portable identity and memory for AI agents through MCP tools for identity, memory, knowledge, harness, and people records.
Load an agent's identity or a worker dossier: creed, preferences, self-model, boot digest, and role/model/client/project/people context.
Store, recall, update, forget, list, and prune memories with categories, TTLs, scope, provenance, and semantic search.
Browse the episode tape, find similar memories, audit memory health, and archive/restore/merge duplicates.
Stage memory proposals, review pending drafts, and ratify or reject them.
Inspect and restore memory revision history.
Edit self-model/preferences sections and bootstrap a fresh agent identity.
Initialize/describe harness manifests and inject managed loom blocks into harness dotfiles.
Manage knowledge pages: write, recall, audit, archive/restore, supersede/move/merge/purge, verify, and restore page revisions.
Manage person cards: write, verify freshness, archive/restore, read/list, view history, and restore revisions.
Run as a local stdio or HTTP MCP server, including an optional knowledge-only scoped daemon.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@loom remember that I'm working on loom"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
loom
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.
The web rebuild goal: docs/how-it-works/ describes
the finished program, page by page, as approved by Jonathan. It replaces the
interim rebuild specs and per-piece parity inventories.
See it whole: docs/architecture.md maps every
moving part (entry points, tool wings, backends, stores) and how they
touch, as diagrams GitHub renders in place.
Demo
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
Related MCP server: HippoDid MCP Server
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, owners, Top of Mind, and requested project/room/mode context. Call this first. A short Pieces index points to on-demand sections:identity({piece: "self-model"}),"harness"(including the client adapter),"last-24h", or"model". Any standard section (including core names such as"creed") can be selected. Passclientormodelwhen loading their manifests; their environment defaults still apply.identity({pieces: ["self-model", "harness"]})loads only those sections;pieceandpiecescombine when both are given.piece: "all"returns the full output, including the legacy memory-index appendix.loom wakekeeps that full output for shell fallbacks. Missing sections are omitted, including missing creed/model/harness files; no placeholder or onboarding error is emitted. Identity text is never summarized or truncated; the 24,000-byte core budget test guards the measured Art baseline, not arbitrary agent-authored files. The shared contract insrc/identity/sections.tsdefines each section’s name, purpose, writer, boot policy, load trigger and advisory UTF-8 byte budget. Every agent uses this table; the core/index/selection are derived from it. Requested room/project/mode blocks and recorder warnings remain supplements. Section budgets never truncate text.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 acategory: episodenote (where it was / what was said or decided / what shipped / what's open; 48h TTL by default) and every body can load the last 24h as a plain time-ordered tape withidentity({piece: "last-24h"}). The full output (piece: "all"orloom wake) includes it 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_recompute_salience— refresh stored salience from timestamps (the consolidation lane's step after the audit); derived and idempotent.Tools a piece offers (a household served over HTTP): an installed piece's
mcp_tools(docs/extensions.md, "Offers") are added to an agent's session, called as that agent. The runtime'srelay(ask another agent something; its body gets it on therelayvenue, and the answer comes back the same way) is one: with no runtime there's no relay tool. Who may relay to whom is the runtime's permissions.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_merge— consolidate 2+ memories into one canonical row. Acts on amemory_auditduplicate-finding: sources are archived with a tombstone and a supersession pointer to the target, the target's times-seen counter sums in each source's count, and bodies can optionally be concatenated. Unlikeforget/memory_archiveon a duplicate pair, this consolidates both sides into one row instead of only discarding one.memory_history— body-revision history for a memory.update()snapshots the displaced body intomemory_revisionsbefore overwriting it. List a memory's snapshots (id, op, replaced_at, char count), or read one snapshot's full content byrevision_id. To put a snapshot back, usememory_revision_restore.memory_revision_restore— restore a snapshotted memory body back onto the memory. Snapshots the current body first, so restore is never destructive. Usememory_historyto list revision IDs before calling this.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 separateproposalstable, invisible torecall,memory_list,find_similar, and the boot digest.memory_proposestages a draft;memory_proposalslists what's pending;memory_ratifycommits one through the same validated write path asremember(an invalid proposal is refused and stays pending);memory_rejectdiscards 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 topreferences.mdandself-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 MCPclientInfo.name. A harness can only describe itself, never another — the target is the connected peer, not a caller-supplied name.harness_patch— edit one small piece of the connected harness's own manifest by exact find/replace, applied against the server's own on-disk copy. Unlikeharness_describe, the caller never has to hold the full current body — which matters once a manifest has grown past the point whereidentity()'s combined payload truncates it (the manifest is read back viaidentity({piece: "harness"}); older clients bundled it with persona, preferences and self-model into one payload capped by the transport; aharness_describecall built from a truncated read would silently drop everything past the cut on the next overwrite).findmust match the current body exactly once.knowledge_write— upsert an entity page by slug into the knowledge store (a separateknowledge.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 storedprovisional. 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; stampslast_accessed/hit_count) andindex(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_list— every active page's freshness fields (no bodies): what a verification sweep picks from, asloom knowledge listgives it.note_write— write one of the agent's notes, whole: a plan, a brief, a write-up, a run's findings. A new note needs its lifespan:keep(never expires),while(60 days after its last change) orshort(14 days). An expired note goes at the next sweep (loom note sweep) unless a live memory or knowledge page cites it (note:<path>) or it's pinned. Files attach withloom note attach, stored once by their bytes besidenotes.db.note_read— a note's text, lifespan, expiry and files.note_list— the notes under a prefix, newest first (no text).conversation_digest— a body run's digest of its conversation (what was asked, decided and done;needs_ownerputs it in the owner's Inbox), for the conversation and run given toidentity. A conversation is core's record of who, where and when, in any venue, and never holds text (docs/specs/conversations.md).conversations— the agent's conversations, newest first, filtered by person, project, venue orsince.conversation— one conversation: its record, digests, findings and render (the venue's own, else core's generic one).conversation_findings— graders' findings on the agent's own turns.comms_title— name a Comms thread (a conversation in loom's own app), at most 60 characters, for the conversation given toidentity; never over the owner's own name for it (docs/specs/comms.md).comms_thread— read, read only, a Comms thread of the agent's own: its messages as the owner sees them (words for the household'scomms_days, 14 at most), its replies, tool cards and error cards. This body's own thread, or one named by id; never another agent's.describe_self— write the agent's own description on its loom profile (its window's header), one or two plain sentences, only when the household's owner has asked for it from the agent's window (Regenerate); never its creed or its memories.knowledge_archive— soft-retire a knowledge page (setsstatus='archived'with an optional tombstone note). Archived pages are excluded from recall and maintain but remain recoverable viaknowledge_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 thesupersessionstable. The dedup-merge primitive: write the canonical page withknowledge_write, then callknowledge_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 — useknowledge_mergeinstead.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). Passhard_delete_losers=trueto 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 (callknowledge_archivefirst). All slugs in a batch must be archived; any active slug rejects the entire batch with no mutation.confirm: trueis 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: setsverified_atand optionallyfreshness_anchor. The verification engine's primitive — recording "claims still hold" must never go throughknowledge_write(a verify run once replaced 13 page bodies with its notes). An optionalnoteappends a dated## Verificationsection (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 intopage_revisions(newest 10 kept per page). List a page's snapshots, read one byrevision_id, orrestore: trueto 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.Person cards —
person_write,person_verify,person_archive,person_restore,person,person_list,person_history,person_revision_restore,person_evidence(the tagged memories a card condenses, asloom person evidencegives them),person_merge(two cards that turn out to be one person become one: from is left as a redirect to into, and everything tagged from is re-tagged). A card is the condensed current state of one human the agent works with (where they are in each system, with a freshness marker; how to work with them; what they were said to be allowed to do, each with a source). One value per field, overwritten; the past lives in revisions. Cards are descriptive, never a grant: the harness's gating names (tier,scope, …) are rejected on write.identity({people: [slug, ...]})adds an# In the roomblock with the cards of the people a turn is addressed by. CLI:loom person show <slug>/loom person list. Design:docs/specs/person-cards.md.Project cards —
project_write,project_verify,project_archive,project_restore,project_history,project_revision_restore,project,project_list,project_hub,project_orphans. A project card is the condensed current state of an ongoing body of work (what it is, its goal, where it stands, with freshness markers) pluslinks, the selectors its hub reads with: aliases (other memory tags that mean this project), note prefixes, an epic, repos, venues. The hub is computed at read, never stored: memories tagged with any of the project's names, notes under its prefixes, and person cards with awherefield for it. A project's names (slug and aliases) are unique across live projects, and recall scoped to any of them sees memories tagged with any of them;forgetandmemory_liststay exact.identity({project})adds a# This projectblock with the card.project_orphanslists memory tags no project answers to. CLI:loom project show|list|hub|orphans. Design:docs/specs/projects.md.
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
The stack
loom ships one opinionated stack:
Storage —
better-sqlite3+ thesqlite-vecvec0 virtual table. Onememories.dbper 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 insrc/backends/embedding-runtime.ts— it started as thefastembedpackage, which was archived upstream while pinned to atarline 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;
enginesrequires ≥ 22).
That's it.
Install the setup skill
npx @jbarket/loomai installA 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:
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.mdFinish setup inside the harness
Open your chosen harness. Run the skill:
Claude Code —
/loom-setupCodex / 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.
# 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 8787Host, port, and an optional bearer token come from flags or environment:
Variable | Flag | Default | Description |
|
|
| Interface to bind |
|
|
| Port to listen on |
| — | (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.
Knowledge-only scope — a second identity without memory tools
loom serve --http --scope knowledge starts a second, standalone daemon
that registers only the knowledge_* tools — no identity,
remember/recall, or any other memory-wing tool is on its surface.
This is how a second identity (e.g. a teammate's agent) can read/write a
shared knowledge store without ever being handed access to memory. Same
bind-safety as above; auth is a per-identity bearer instead of one
shared token, so the acting identity is derived from which token was
presented — never from a request field — and a session is pinned to
whichever identity opened it.
LOOM_KNOWLEDGE_BEARER_TOKENS="art:abc123,mark:def456" \
loom serve --http --scope knowledge --port 8788Variable | Flag | Default | Description |
|
|
| Port to listen on |
| — | (required) |
|
Both scopes share the same backing store (knowledge.db under the
context dir) and the same tool implementation — the full server (identity
hardcoded to its own name) and the scoped service go through the exact
same registration code, so there's no separate "local" code path that
could drift from the one the scoped service uses.
Session and stream behavior
One server per session. Each MCP session (keyed by the
mcp-session-idheader) 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
413before the handler runs.SSE keep-alive heartbeat. The server drives a protocol-native
pingto 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),
so a single daemon serves multiple harnesses correctly.
The CLI against a remote loom
The store verbs (wake, recall, remember, update, forget,
memory, knowledge, person) can run against a daemon instead of a
local stack, so hooks and scripts that shell out to loom keep working
when loom lives on another host or the agent runs in a container:
export LOOM_URL=http://100.94.0.12:8787/mcp # or --url per call
export LOOM_TOKEN_FILE=/run/secrets/loom-token # the bearer token, read from a file
loom recall "meeting preferences"
echo "Prefers async updates" | loom remember "working style" --category user --jsonThe CLI posts the argv (and a remember/update body from stdin, or from
your local $EDITOR) to POST /cli next to the MCP URL. The daemon runs
the same CLI against its own stack and sends back stdout, stderr and the
exit code, so output, --json and exit codes match a local run. The
endpoint sits behind the same bearer gate and payload cap as MCP, takes
only those verbs (each one already has an MCP tool; memory recompute-salience and memory recall-stats have none, so they stay
local), and refuses
--context-dir: it only serves its own stack. It only exists when
LOOM_BEARER_TOKEN is set, and it refuses browser requests (any Origin
header, or a body that isn't application/json). The knowledge-only daemon
has no /cli. Every other command (doctor, inject, serve, …) stays
local, and --url on one of them is an error.
loom's page
The full-scope daemon serves a web page at its root (/; the old /ui/…
addresses redirect). MCP shares the root: a POST, a request with an MCP
session or an event-stream GET is MCP's, a plain browser GET is the page.
Home is the tape:
what every body did in the last day, by hour and by where it happened, with
top of mind and the people cards that need a look beside it. Mind lists
every memory by heat and says why each one has it, which is how you find a
memory that shouldn't be in what the agent wakes up holding. One memory and
People (each card, with what's newer than it) are a click away.
Everything else comes from installed pieces. A piece that answers
ui --json gets a tab, a tile on Home and items under "Your call", and its
own pages and forms: the task queue, the secrets store (write-only: add and
replace, never read back), the chat bridges. Nothing to configure: install a
piece and it shows up, uninstall it and it's gone. loom never names a piece
(docs/extensions.md, "The page").
In a household (docs/specs/household.md)
the page is the owner's view of all of it:
Home shows every agent (what it's doing, from its tape), the tape across all of them, and the commons at a glance.
Knowledge is the commons' pages.
People is the directory, and each person's page shows every agent's relationship with them.
/a/<agent>is one agent's own view (its tape, Mind and people) plus Setup: its identity (read-only), its tokens (make one, shown once; revoke), and health.Add an agent creates its stack and hands over its first token. It's served at once, without a restart.
The page needs LOOM_BEARER_TOKEN. A daemon with no token serves none
(403), the same rule as /cli, because any site that DNS-rebinds a name to
the loopback address could read an open page. Log in once with the token. The
browser gets a session: a random id the daemon keeps in memory. It's not the
token, it can't be replayed against /mcp or /cli, and it can't be used to
guess the token. It lasts 30 days, until you sign out (which revokes it), or
until the daemon restarts. Every form carries an anti-forgery token bound to
that session, a cross-site post is refused, and another site can link to the
page but not embed or fetch it. A form's fields go to the piece on stdin, and loom never logs, keeps
or puts them in a URL. Scripts can send the bearer header instead (for
example /pieces.json for the pieces' manifests). The page runs no script
and is served under a CSP that forbids script and framing. Pieces never
receive loom's bearer tokens.
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:
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
# 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-agentWhat 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
with use. A write, an update or a repeat remember makes it fully hot.
A recall adds heat by rank: the top result gets 0.5, the next 0.3 and
0.2, and everything below 0.1, capped at 1. So a memory is hot when it
keeps being the answer, not because it once turned up near the bottom of
someone's results. Heat is computed from those timestamps when the digest is read, so
it can't go stale if the consolidation lane skips a night. 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):
# 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-agentCLI
Every MCP tool has a shell equivalent. Useful for debugging, scripting, or running without a harness.
# 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
# Read a person card (exit 3 when there is none) / list cards and their freshness
npx @jbarket/loomai person show patrick-kells --context-dir ~/.config/loom/my-agent
npx @jbarket/loomai person list --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-agentnpx @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):
loom inject --all >/dev/null 2>&1 || trueIdempotent; 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:
loom migrate
loom migrate --dry-run # check without applying
loom migrate --json # machine-readable outputPieces — loom tasks, loom secrets, … as separate programs
loom stays identity and memory. Everything else an agent leans on (tasks,
secrets, a wake clock, an approval page) is a piece: its own program,
reached through loom's command namespace the way git reaches git-<cmd>.
loom tasks list runs the first loom-tasks on PATH with list, and
passes back its exit code. Core commands can't be shadowed. Pieces never
write loom's stores, work alone, and compose when others are installed. Each
piece role has a contract, so an implementation can be swapped for another.
loom pieces # what's installed (name → path)
loom tasks ready # → loom-tasks readyThe rules, the dispatch details and how pieces compose:
docs/extensions.md.
The household — several agents on one loom
One loom can serve several agents, with a shared commons
(docs/specs/household.md). A household is a
directory ($LOOM_HOME, default ~/.config/loom) with a household.json,
a tokens.json, and one context dir per agent under agents/. A plain
context dir with no household around it is a household of one and works
exactly as before.
loom household init art # ~/.config/loom/art → agents/art (a symlink stays)
loom household add mark # an agent whose dir already exists under agents/
loom household commons # once, daemons stopped: knowledge.db → commons/ (shared by every agent)
loom token create --agent art --label "Art · house on wunder" # printed once
loom token create --owner --label "Jonathan · page"
loom token list
loom token revoke "Art · house on wunder"
loom token link --agent --label "screenshots t-1871" # an agent's one-time page sign-in, its session named
loom sessions list # every browser signed in to the page, by ref
loom sessions revoke 3f9a0c1d2e4b5a69 # sign that one browser out; every other stays
loom sessions revoke --label "screenshots t-1871" # an agent ends its own sessions when doneEvery token has a role. agent:<name> is MCP and /cli as that agent:
its own stack only. owner gets the default agent, or another at
/agents/<name>/ on the daemon, and the page. peer:<name> gets
knowledge tools only. The daemon resolves the role on every request; no tool
takes an agent argument, so a body can only be the agent its token names.
LOOM_BEARER_TOKEN, when set, is an owner token too. A daemon whose context
dir is <home>/agents/<name> next to a household.json serves the whole
household. A process with LOOM_HOME set and no context dir uses
LOOM_AGENT, or the household's default.
The bundle — the household on a USB stick
loom export --to household.bundle --recipient age1… # your key, never the box's
loom restore household.bundle --identity ~/owner.key --drill # does it really come back?
loom restore household.bundle --identity ~/owner.key --to ~/.config/loom # on a new machineloom export writes the whole household into one file, encrypted with
age to a recipient the owner holds (a YubiKey,
or a key kept in a password manager). The file contains:
the household's files and tokens;
the commons;
every agent's directory. Databases go through SQLite's backup API, never as a raw copy of a live file. Old
*.bakfiles andbackup-*folders are left out.each installed piece's own part (
loom-<piece> bundle export), which the piece encrypts itself to the same recipient. Core never sees inside it.
A plain context dir exports as a household of one.
loom restore lays a bundle down in an empty LOOM_HOME (never over a
live one). It then hands each installed piece its part (loom-<piece> import, with LOOM_IMPORT_IDENTITY naming the key so the piece can
re-encrypt for the new machine). A piece that isn't installed yet keeps its
part in pieces-pending/.
--drill restores into a throwaway directory instead and compares the
result with the live household: identities, memory counts, every card,
knowledge, tokens. Nothing live is touched.
The nightly backup
loom backup set --target git:https://github.com/you/household-backup.git --recipient age1… \
--at 02:55 --tz America/Chicago --keep 7 [--require box --require secrets]
loom backup status # the last good one, its drill, what's wrong now
loom backup run # one nowloom backup does the bundle every night by itself
(docs/specs/keeping-watch.md): it exports the household, encrypted to your keys
and to the machine's own drill key ($LOOM_HOME/backup/drill.key, made there,
never in a bundle), restores it into a throwaway home and compares it with the
live one, and only then writes it to the target:
git:<url>: a repo loom owns. The branch is always one commit holding the newest--keepnights and each month's first, force-pushed with a lease. A bundle over 90 MB goes in parts. It pushes with this user's own git credentials; loom stores none, and refuses a URL that carries one.path:<dir>: a directory (a USB stick, a NAS), the same bundles as files.
A target holding anything loom didn't write (no .loom-backup) is refused. The
default agent's Setup shows the last run; a failed or missed one (none good in
26 hours) is an alert in the household owner's Inbox, and the daemon's
LOOM_ALERT_COMMAND (a JSON argv in its environment, never a household
setting) hears it as loom-backup --severity bad --summary …. A household
restored from a bundle waits for loom backup set before it pushes anywhere.
A restore trusts what's in the bundle. age encrypts, but it doesn't prove who
made the file, so only restore bundles you made. Needs the age and tar
programs.
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.
Or patch it in place. Once a manifest exists, harness_patch edits
one piece of it by exact find/replace against the server's own on-disk
copy — no need to read the full current body back through identity()'s
combined payload first (which truncates past a size cap, so a
read-truncated-then-overwrite via harness_describe risks silently
losing whatever was past the cut). find must match the current body
exactly once; zero or multiple matches is refused.
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:
---
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 |
|
| Path to agent's context directory |
|
| Override the memory DB path |
| (on) | Set to |
|
| fastembed model ID |
|
| Where to cache ONNX models |
|
| Where model tarballs are fetched from on first run |
| (unset) | Model identifier for model-manifest context: |
| (unset) | Client adapter hint: |
|
| Bind host for |
|
| Bind port for |
| (unset) | Bearer token required on every HTTP request when set |
|
|
|
| (unset) | Run the CLI's store verbs against this loom-http (its MCP URL) instead of a local stack |
| (unset) | File holding the bearer token for |
|
| Bind port for |
| (unset) |
|
--context-dir <path> works as a CLI alternative to
LOOM_CONTEXT_DIR.
See .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>.mdRoadmap
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.The boot digest — salience-tiered
# Top of Mindview assembled at identity-load;loom memory digest/recompute-salience.Harness self-describe —
harness_describelets a runtime author its own manifest, with data-drivenanswersToresolution.Capture-propose queue —
memory_propose/memory_proposals/memory_ratify/memory_reject: drafts ratified before they become canon.
Still tracked in the open:
Project board — live status of what's in flight, queued, and shipped.
v0.4 roadmap discussion — 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/architecture.md— loom at a glance: every moving part and how they touch. A contract test fails CI when a new tool, subcommand, backend module or table isn't on it.docs/troubleshooting.md— install failures, MCP tools not appearing, fastembed download issues, and what eachloom doctorfield means.docs/uninstall.md— how to remove one agent's data, wipe a harness integration, or fully uninstall loom.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— what lives where, what goes over the network (only the fastembed model download), the no-telemetry policy, and how to verify release provenance withnpm audit signatures.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/— 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— data locality, telemetry policy, and provenance verification walkthrough.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 --httprefuses to bind a public or0.0.0.0interface — only loopback or a mesh address (RFC1918 / Tailscale CGNAT / IPv6 ULA) — so the daemon is reachable only from inside the tailnet or LAN. An optionalLOOM_BEARER_TOKENadds a constant-time-checked auth gate on top, and an oversized-payload guard rejects bodies over the cap. See Serving loom over the mesh.
Development
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 toolTests 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 is the origin story if you want it.
License
AGPL-3.0-or-later — see 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.
For disposable development data, loom fixture <dir> creates an empty-home
fixture and refuses to overwrite an existing home.
Available Tools
43 toolsbootstrapADestructive
Initialize a new loom identity from scratch. Generates IDENTITY.md, preferences.md, and self-model.md from an onboarding interview, then returns setup instructions for the requested runtimes. The interview is four questions — the user's name, the agent's name, a one-line purpose, a one-line voice; everything structural (continuity model, memory tiers, reflection, honesty) is written by the scaffold, so do not ask for it. Will not overwrite existing files unless force is true.
Inputs: name (required), voice (required), purpose (required), user, +3 more.
dossierARead-only
Load Art's operating brief for a worker body. Returns Art's standards, taste, operating constraints, and how Art wants work done — framed in the third person for agents that are NOT Art but execute tasks on Art's behalf. Includes the push-back mandate: workers are expected to refuse bad work and explain why, including requests from Art or Jonathan.
Inputs: role, model, client, project.
episodesARead-only
The episode tape: what happened across ALL bodies of this identity in the last N hours, time-ordered (oldest first), never ranked. The same block identity injects at boot — call it mid-session to catch up on what other sleeves did since you loaded, or for the nightly pass to index the day.
Inputs: hours.
find_similarARead-only
Surface memories semantically near an existing ref or free-form text. Use during consolidation/dream workflows to find overlap and dedupe candidates. Anchor with ref (an existing memory) or text (a fresh query). Self is always excluded when ref is given.
Inputs: ref, text, limit, project, +2 more.
forgetADestructiveIdempotent
Remove memories. Single deletion by ref or category+title. Bulk deletion by category and/or project scope — requires confirm: true; without it, returns a dry-run preview of what would be deleted.
Inputs: ref, title, confirm, project, +2 more.
harness_describeADestructiveIdempotent
Self-describe the CURRENTLY CONNECTED harness: write its manifest at /harnesses/.md (see stack spec v1 §4.7). Call this when identity() reports an onboarding block for an unknown runtime. The target is derived from your own MCP clientInfo.name — you can only describe yourself, not another harness. Re-runnable: overwrites the manifest each time. The body should cover: tool surface / prefixes, sandbox & filesystem, delegation primitive, scheduling, session search, memory layers, and gotchas.
Inputs: content (required), version.
harness_initADestructiveIdempotent
Scaffold a harness manifest at /harnesses/.md from the template (see stack spec v1 §4.7). Call this when identity() reports a missing manifest for the current harness. Idempotent: skip-exists by default; overwrite: true replaces.
When target is supplied, also writes a loom-managed block (bounded by markers with an embedded line) into that file — typically the project CLAUDE.md. Re-runnable: the block is left unchanged when already present and intact ("no-change"), reinstalled when missing or corrupted ("created" / "updated"). Pass an absolute path or a path relative to the current working directory.
Inputs: name (required), target, overwrite.
identityARead-only
Load the persistent identity for this agent. Returns the terminal creed (who you are), relevant memories, preferences, and self-model. IMPORTANT: Call this tool FIRST before doing any other work. The identity defines who you are and how you should behave.
Inputs: role, model, client, people, +1 more.
knowledge_archiveAIdempotent
Soft-retire a knowledge page: set its status to archived with an optional tombstone note. Archived pages are excluded from knowledge_recall and knowledge_maintain but remain in the database and are fully recoverable via knowledge_restore. Use this instead of deletion when the page may need to be audited or recovered. For deduplication merges, prefer knowledge_supersede which archives and records the relationship.
Inputs: slug (required), note.
knowledge_historyADestructive
Body-revision history for a knowledge page. Replace-writes snapshot the displaced body into page_revisions (newest kept, capped per page) — this tool is the recovery surface. Three modes: slug alone lists snapshots (metadata only); slug + revision_id reads one snapshot's full body; adding restore: true puts that body back on the page (the displaced body is snapshotted first, so restore is never destructive).
Inputs: slug (required), restore, revision_id.
knowledge_maintainARead-only
Read-only health report for the knowledge store. Four branches: (1) expansion candidates — thin body + high hit_count (needs deepening); (2) cold pages — not accessed recently (unused or undiscovered); (3) misfile audit — provisional sourcing or conversation-only citations (world/ class: should be in the memory store instead — including pages that drifted in as personal/inner-monologue content rather than shared-ready synthesis, which matters more now that knowledge is read by other identities and by Jonathan, not just you; ours/ class with internal sourcing are NOT misfiles — they are correct); (4) person-page check — an active page whose slug or title names a person card (its slug or exact name, whole words) may belong on the card instead; a report, not enforcement. Only the full loom server runs (4); the knowledge-only server says it was not run. Cold/expansion ranking reads the shared hit_count/last_accessed aggregate (any reader's access keeps a page warm), not a per-identity breakdown — per-reader stats exist (knowledge_access) for attribution, but splitting cold-ranking by identity would make the list miss pages a different reader keeps alive. Pair with knowledge_write to act on findings.
Inputs: cold_days, thin_body_threshold, expansion_hit_threshold.
knowledge_mergeADestructive
Consolidate 2+ knowledge pages into one canonical page. Re-parents all citations from source pages to the target, deduplicating by (claim, source_kind, source_locator, excerpt). Takes MAX(verified_at) across all pages. Losers are superseded: archived with a tombstone and a supersessions pointer to the target. Loser bodies are returned in the result for curator review; set append_loser_bodies=true to concatenate them. Use knowledge_write first if the target body needs updating before merging. Distinct from knowledge_supersede (1:1 pointer, no citation consolidation) — use merge when consolidating data from multiple pages into one.
Inputs: target_slug (required), source_slugs (required), note, hard_delete_losers, +1 more.
knowledge_moveA
Re-key or re-domain a knowledge page in place — same row, same uuid, citations and verification history preserved. Three modes: (1) Single-page: provide slug + new_slug and/or new_domain. Slug rename writes a supersessions pointer (old→new) unless leave_pointer=false. If new_slug already exists, the call is rejected — use knowledge_merge instead. (2) Batch by slug list: provide slugs array + new_domain to re-home multiple pages atomically. (3) Batch by domain prefix: provide from_domain_prefix + to_domain_prefix to re-home a whole subtree in one transaction.
Inputs: slug, slugs, new_slug, new_domain, +3 more.
knowledge_purgeADestructive
Hard-delete one or more archived knowledge pages and cascade their citations. Archive-first guard: rejects any page that is not already archived — call knowledge_archive first. All slugs must be archived; a mixed list (any active) rejects the entire batch with no mutation. confirm: true is required explicitly to prevent accidental irreversible deletes. Supersession pointers in the supersessions table are NOT removed (historical record preserved). Use this to clean up tombstoned cruft after merge/supersede workflows — not for retiring active pages.
Inputs: slugs (required), confirm (required).
knowledge_recallA
Search the knowledge store with LIKE matching over title, body, and domain, or fetch one page exactly by slug. Never surfaces archived pages. Two detail tiers: "full" returns whole entity pages (the synthesis unit) and stamps last_accessed/hit_count; "index" returns compact slug/domain/snippet entries without stamping. Defaults: full when a query is given, index when browsing without one. Full output is size-guarded — overflow results degrade to index entries; recall by slug to read them. Prefer slug over query when you know the page — token matching can hit cross-references in other pages' bodies.
Inputs: slug, limit, query, detail, +2 more.
knowledge_restoreAIdempotent
Restore a previously archived knowledge page back to active status. Clears the archive flag and tombstone note. The page becomes visible to knowledge_recall and knowledge_maintain again.
Inputs: slug (required).
knowledge_supersedeAIdempotent
Mark one knowledge page as superseded by another, then archive the old page. Records the supersession relationship in the supersessions table. This is the dedup-merge primitive: write the canonical page with knowledge_write, then call knowledge_supersede(old_slug=loser, new_slug=canonical). Both pages must already exist. old_slug is archived with a tombstone pointing to new_slug.
Inputs: new_slug (required), old_slug (required), note.
knowledge_verifyA
Stamp a knowledge page as verified WITHOUT touching its body — sets verified_at and optionally freshness_anchor, and records an attributed verification (verifier, outcome, whether citations were checked) — the verifier is always YOUR loom identity, resolved server-side, never a field you can set. This is the verification engine's primitive: use it (never knowledge_write) to record "claims still hold". An optional note appends a dated "## Verification" section to the body (append-only, single-page mode). Batch mode (slugs) stamps many pages with a shared timestamp; archived pages are rejected; a batch with any unknown slug is rejected whole.
Inputs: note, slug, slugs, outcome, +3 more.
knowledge_writeADestructive
Upsert a knowledge page by slug. Two classes:
world/ (default) — facts true independent of us. Domain = "music/gear", "software/loom", etc.
ours/ — Art-created artifacts, revised-in-place (breakbrain density model, homelab design,
wake-chain spec, script templates). Domain starts with "ours/", e.g. "ours/art-ops".
On an existing slug: body REPLACES by default (mode: "append" adds to it instead), title/domain follow the write, citations always appended with exact-duplicate dedup — safe to re-send.
Epistemic gate (§E1):
• conversation-only citations → provisional (both classes).
• ours/ domain + any repo citation → internal (ours/ class artifact; repo = git path / commit / live-system probe).
• any web/repo citation on a non-ours/ domain → sourced (world/ default).
NOTE: repo citations on world-class pages (domain not starting with "ours/") are treated as sourced, not internal.
A citation to github.com/someone-else/project is a world source.
World filing test: knowledge must be true independent of Jonathan. For our own artifacts use ours/.
Shared surface, not a scratchpad: knowledge is readable by other identities (e.g. Mark) and by Jonathan, not just you. Write pages as finished synthesis for that audience — no raw inner-monologue reasoning, no private-to-you deliberation, nothing that assumes only you will ever read it. A personal reflection or working-out-loud note belongs in remember, not here.
Inputs: body (required), title (required), domain (required), citations (required), +5 more.
memory_archiveAIdempotent
Soft-retire a memory: move it to the archive tier with a tombstone instead of deleting it. Archived memories are excluded from recall, list, audit, and find_similar but remain fully recoverable via memory_restore. Use this instead of forget when the memory may need to be recovered or audited later.
Inputs: ref, note, title, category.
memory_auditARead-only
One-shot health report for the memory store: totals, category breakdown, stale memories (untouched beyond threshold), near-duplicate pairs (above similarity threshold), and expired refs. Read-only — pair with forget/update to act on findings.
Inputs: stale_days, max_duplicates, similarity_threshold.
memory_historyARead-only
Body-revision history for a memory. update() snapshots the displaced body into memory_revisions before overwriting it — this tool is the read surface. Two modes: ref alone lists snapshots (metadata only — id, op, replaced_at, char count); ref + revision_id reads one snapshot's full content. To put a snapshot back, use memory_revision_restore.
Inputs: ref (required), revision_id.
memory_listARead-only
Browse memories without semantic search. Lists memories with optional category/project filters. Useful for auditing, maintenance, and discovery.
Inputs: limit, project, category.
memory_mergeADestructive
Consolidate 2+ memories into one canonical row. Acts on a memory_audit duplicate finding: pick the survivor (target_ref) and fold the rest (source_refs) into it. Sources are archived with a tombstone and a supersession pointer to the target (same mechanism as memory_archive/supersede, N:1 instead of 1:1); the target's times_seen sums in each source's count. Unlike forget/archive on a duplicate pair, this consolidates both sides into one row instead of just discarding one.
Inputs: target_ref (required), source_refs (required), note, hard_delete_losers, +1 more.
memory_proposalsARead-only
List all pending proposals in the capture-propose queue, newest first. These are DRAFTS awaiting ratification — they are not part of memory and do not appear in recall, memory_list, find_similar, or the boot digest. Ratify one with memory_ratify or discard it with memory_reject.
Inputs: no named parameters.
memory_proposeA
Stage a DRAFT memory in the capture-propose queue for later ratification. A proposal is NOT an authored memory: it is invisible to recall, memory_list, find_similar, and the boot digest until it is ratified via memory_ratify. Use this when a background lane wants to suggest a write without committing it — the human (or Art) reviews and ratifies before it becomes canon. Drafts may be rough; validation runs at ratify time.
Inputs: title (required), content (required), category (required), ttl, +3 more.
memory_pruneADestructiveIdempotent
Remove expired memories (TTL elapsed). Use dry_run to preview without deleting.
Inputs: dry_run, stale_days.
memory_ratifyAIdempotent
Ratify a pending proposal into a REAL memory. Loads the proposal, applies any optional overrides (your edits on accept), and commits it through the same validated write path as remember — so an invalid proposal is refused with its typed reason and stays pending. On success the memory becomes recallable and the proposal is removed from the queue. This is the gate: no proposal becomes canon without it.
Inputs: id (required), ttl, title, content, +2 more.
memory_rejectADestructiveIdempotent
Discard a pending proposal without committing it. Deletes the staging row; no memory is written. Use this for drafts that should not become canon.
Inputs: id (required).
memory_restoreAIdempotent
Restore a previously archived memory to the active set. Clears the archive flag and tombstone note. The memory becomes visible to recall, list, audit, and find_similar again.
Inputs: ref, title, category.
memory_revision_restoreADestructive
Restore a snapshotted memory body back onto the memory. Snapshots the current body first, so restore is never destructive. Use memory_history to list revision IDs before calling this.
Inputs: ref (required), revision_id (required).
personARead-only
Read one person card: {found, rendered, card, archived, updated, synthesized_at}. A missing card is {found: false}, not an error. where fields carry a freshness marker: [ok], [unverified], or [STALE d] — never trust a stale one without re-checking.
Inputs: slug (required), include_archived.
person_archiveA
Soft-retire a person card with a tombstone (who, when, why). An archived card is left out of identity's room block and person_list, and rejects writes until person_restore.
Inputs: slug (required), reason (required).
person_historyARead-only
Revision history of a person card, newest first: id, op, replaced_at. Every stored change snapshots the previous card; the newest 10 are kept. Use person_revision_restore to put one back.
Inputs: slug (required).
person_listARead-only
List person cards with slug, name, archived, updated, synthesized_at, stale and unverified field counts, and memories_since_synthesis (tagged user memories newer than the summary — how the consolidation lane finds summaries that have fallen behind).
Inputs: include_archived.
person_restoreA
Reactivate an archived person card, fields intact.
Inputs: slug (required).
person_revision_restoreADestructive
Put a person card back to a revision from person_history (card and its synthesized_at). Snapshots the current card first, so it is never destructive. Archive state is unchanged.
Inputs: slug (required), revision_id (required), store.
person_verifyA
Stamp where fields on a person card as checked: sets verified_at (default now) and, if passed, source. Values are not changed. All-or-nothing: an unknown field rejects the call. A failed check is recorded by not stamping.
Inputs: slug (required), fields (required), source, verified_at.
person_writeA
Write a person card — the condensed current state of what you know about one human (not a knowledge page, not the memories: those stay the evidence). merge (default true) merges where/how one level deep (a field passed as null is removed), and replaces name, summary and may when passed; merge: false makes the card exactly what was passed. Passing summary says "I re-read the evidence and this is still right" and moves synthesized_at. Reserved keys (tier, field, projects, scope, trust) are rejected: gates stay in the harness. Worker bodies must not call this — cards are written by Art.
Inputs: slug (required), how, may, name, +3 more.
recallA
Retrieve memories relevant to a query or topic. Returns matching memories from the persistent store. Use this when you need context from past sessions. Results are re-ranked for diversity (MMR, λ=0.7 by default) so near-duplicate memories on a well-covered topic don't crowd out different ones; the top result is always the most relevant. Pass diversity: 0 for pure relevance order.
Inputs: query (required), limit, project, category, +1 more.
rememberA
Store an episodic memory that persists across sessions. Use this when you learn something important about the user, a project, or yourself that should be available in future sessions.
Inputs: title (required), content (required), category (required), ttl, +5 more.
updateADestructive
Update an existing memory. Find by ref (returned from remember) or by category+title. Can replace content, update metadata, or both.
Inputs: ref, title, content, category, +2 more.
update_identityADestructive
Update your self-model or preferences with section-level precision. Targets H2 sections in identity files. Call without section/content to list available sections. IDENTITY.md (the creed) is immutable — only self-model and preferences can be edited.
Inputs: file (required), mode, content, section.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 43 tools
Many tools have carefully written boundaries, but the memory/knowledge lifecycle surfaces overlap heavily: memory_archive vs memory_merge vs forget vs memory_prune; knowledge_archive vs knowledge_supersede vs knowledge_merge vs knowledge_purge; memory_restore vs memory_revision_restore. Descriptions help resolve most cases, but an agent must read closely to choose correctly.
All names use snake_case, but conventions are mixed: domain-prefixed verbs (memory_list, knowledge_write, person_verify) coexist with bare names (identity, episodes, recall, remember, forget, update, dossier, bootstrap) and update_identity instead of identity_update. The pattern is readable but not predictable.
43 tools is heavy for any single server and exceeds the 25+ threshold. While the server spans several domains (identity, memory, knowledge, person, harness), many lifecycle variants inflate the surface, making discovery and selection harder.
The surface covers full lifecycles for memory, knowledge, person cards, and identity, including create/read/update/delete, archive/restore, revision history, verification, proposals, audits, merging, moving, and supersession. No obvious domain operation is missing.
Maintenance
Related MCP Connectors
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Hosted memory for AI agents over MCP. One memory shared by all your agents.
Persistent memory for AI agents to retain, retrieve, and recall conversation context through MCP.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to maintain persistent memory across sessions by capturing conversations, extracting durable knowledge, and injecting relevant context, supporting various MCP-compatible platforms.12MIT
- AlicenseNot gradedqualityDmaintenanceProvides persistent, cloud-based memory for AI agents, letting them remember preferences, skills, and decisions across sessions via an MCP-compatible interface.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to maintain a persistent identity and structured memory—including reasoning patterns, episodic history, and knowledge—while exposing procedures for managing that memory over MCP.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceProvides AI agents with persistent, human-like memory infrastructure via MCP, enabling them to store, search, summarize, and forget episodic, semantic, procedural, and working memories across sessions.280 npmMIT