Provides persistent identity, episodic memory, and a knowledge store for AI agents to maintain context across different sessions and clients.
Also known as sleepunit-agents/loom, @jbarket/loomai
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- 3,375
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- AGPL-3.0
What is loom MCP?
loom provides persistent identity, episodic memory, and a knowledge store for AI agents to maintain context across different sessions and clients.
Summary generated from the project's README
About loom MCP server
Maintaining a consistent persona and long-term memory across different AI sessions is what loom enables for developers using MCP-capable tools like Claude Code, Cursor, or Gemini CLI. By connecting this server to your local environment, your AI agents can carry their specific values, working preferences, and past experiences from one interaction to the next, regardless of which model or client you switch to.
The server provides 31 specialized tools to manage an agent's state. You can use identity to load a terminal creed that defines an agent's purpose, or utilize episodic memory tools like remember, recall, and update to store and retrieve specific events. For structured information, the knowledge store allows for writing and searching entity pages, while the note system handles short-term plans or briefs with specific lifespans.
This setup is designed for users who want their agents to evolve. It includes advanced features like memory proposals for human ratification, a revision history to restore previous memory states, and a dossier tool that reframes an agent's identity for worker bodies executing tasks on its behalf.
What you can do with it
- 1Preserve agent persona across clientsAn agent can load its specific values and voice from a terminal creed when switching between different MCP harnesses.
- 2Manage episodic memory with semantic searchA developer can instruct an agent to recall specific past interactions using vector-based semantic retrieval.
- 3Maintain a structured knowledge baseYou can use the server to store and query truth-independent facts that are separate from conversational memories.
- 4Review and approve memory draftsAn agent can propose new memories to a staging area for a human to ratify before they become permanent.
Written from the project's README. Every use case is checked against a quote from it.
How to install loom MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall loom MCP in Claude Code
$ claude mcp add loom -- npx -y @jbarket/loomaiInstall loom MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"loom": {
"command": "npx",
"args": [
"-y",
"@jbarket/loomai"
]
}
}
}Install loom MCP in VS Code
.vscode/mcp.json
{
"servers": {
"loom": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@jbarket/loomai"
]
}
}
}Install loom MCP in VS Code CLI
$ code --add-mcp '{"name":"loom","type":"stdio","command":"npx","args":["-y","@jbarket/loomai"]}'Install loom MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"loom": {
"command": "npx",
"args": [
"-y",
"@jbarket/loomai"
]
}
}
}Install loom MCP in Codex
$ codex mcp add loom -- npx -y @jbarket/loomaiInstall loom MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.loom] command = "npx" args = ["-y", "@jbarket/loomai"]
Install loom MCP in Gemini CLI
$ gemini mcp add -s user loom npx -- -y @jbarket/loomaiInstall loom MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"loom": {
"command": "npx",
"args": [
"-y",
"@jbarket/loomai"
]
}
}
}Configuration
LOOM_KNOWLEDGE_BEARER_TOKENSLOOM_TOKEN_FILELOOM_URL
| Name | Description | |
|---|---|---|
| LOOM_KNOWLEDGE_BEARER_TOKENS | — | |
| LOOM_TOKEN_FILE | — | |
| LOOM_URL | — |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablesleepunit-agents/loom is public and reachablegithub.com/sleepunit-agents/loom ↗Pass
- Package names this repository as its source@jbarket/loomai names sleepunit-agents/loom as sourcenpmjs.com/package/@jbarket/loomai ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @jbarket/loomainpmjs.com/package/@jbarket/loomai/v/0.16.1#provenance ↗Pass
- Open source license (OSI)AGPL-3.0spdx.org/licenses/AGPL-3.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/sleepunit-agents/loom ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @jbarket/loomaiPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubloom
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.
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
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 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:
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.
# 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.
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 8788
| Variable | Flag | Default | Description |
|---|---|---|---|
LOOM_KNOWLEDGE_HTTP_PORT |
--port |
8788 |
Port to listen on |
LOOM_KNOWLEDGE_BEARER_TOKENS |
— | (required) | "identity:token,identity:token" — refuses to start if empty |
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.
loom MCP questions
How do I add loom MCP to Claude Code?
Run claude mcp add loom -- npx -y @jbarket/loomai in your terminal. Add --scope user to make it available in every project.
How do I add loom MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Can I use loom with Claude Code or Cursor?
Yes, loom is designed to be configured into MCP-capable harnesses like Claude Code, Cursor, Codex, and Gemini CLI.
How does the memory recall work?
It uses episodic memory with semantic (vector) recall, allowing for category filtering and optional TTL.