Connect Loom to Claude Desktop and ask your vault anything. Loom is a local MCP server that gives Claude cited answers from your notes — nothing leaves your machine. Claude Desktop, Cursor, or any MCP client works. → Setup below.
Point it at your notes folder. Loom indexes everything, maps typed relationships between ideas (which notes cite the same sources, which contradict each other, which extend the same argument), and builds a persistent graph that gets smarter as you add more. Your vault, vector index, and graph stay on your machine. Only the specific passages behind an answer go to Claude for synthesis — or skip that and run a local model instead.
What this lets you do that search can't: ask "what connects my notes on topic A and topic B" and get the actual relationship chain, not just documents that mention both. Ask "what have I been reading extensively but never synthesized" and get your blind spots surfaced through graph centrality. Those are structural queries — they need a graph, not a bigger context window.
Who this is for: researchers, lawyers, clinicians, journalists, and anyone with thousands of documents who needs to reason across all of them privately, on their own machine. If 50 notes and grep is enough, this is overkill. If you have 5,000 and you've started forgetting what you know — that's exactly what Loom was built for.
Query: "Search my vault first, then answer" — a clinical polypharmacy question about a 74-year-old CHF patient. Loom retrieved passages from her clinical reference notes on Beers Criteria and drug interactions. Claude synthesized across them — flagging the ibuprofen contraindication, oxybutynin's ACB score of 3 as the likely cause of confusion and falls, and the triple AKI risk.
Query across a research vault — Loom pulled from Cornell CS4780 lectures, a standalone SGD note, and papers, then identified a gap: no dedicated note on adaptive methods (Adam, AdaGrad, RMSProp).
Related MCP server: brainMD
Windows: Download loom-installer.exe and run it. No Python or Neo4j required. The installer handles setup and connects Claude Desktop automatically.
Mac / Linux: Install from source with pipx:
git clone https://github.com/KlossKarl/loom
cd loom
pipx install . # includes the embedded graph backend (FalkorDB) — no server needed
loom init # interactive wizard: pick your vault folder
loom chatloom init walks you through picking a vault folder, then loom chat is live. On Mac/Linux the full knowledge graph is on by default via an embedded FalkorDB backend that installs with Loom itself — no Neo4j, no Docker, no server (requires Python ≥ 3.12; older Pythons run vector-only). On Windows, embedded vector-only mode is the default and Neo4j is the optional graph upgrade. Full options (Docker, dev install) are in Install below. On a Mac? See the Mac setup guide for the pip3/python3 conventions and SSL/cert notes.
Loom runs as a local MCP server (loom_mcp.py) that connects your vault and knowledge graph to Claude Desktop, Cursor, Continue.dev, or any MCP-compatible client. You ask questions in Claude Desktop; Loom does the retrieval locally and returns cited passages and graph connections.
Setup (Claude Desktop):
Install Loom from source (see Install) and run loom init once. The
wizard auto-detects your OS paths, writes config.yaml, and registers Loom in
Claude Desktop's config automatically on Windows and Mac. The next two steps are
only needed if you want to wire it up by hand.
Add Loom to your Claude Desktop config: %APPDATA%\Claude\claude_desktop_config.json
on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on Mac:
{
"mcpServers": {
"loom": {
"command": "python",
"args": ["C:\\path\\to\\loom\\loom_mcp.py"]
}
}
}Restart Claude Desktop. Ask: "Search my vault for anything about knowledge graphs."
On Windows, if
pythondoesn't resolve in Claude Desktop's environment, use the full interpreter path (e.g.C:\\Python314\\python.exe). Full instructions (Mac paths, thepythonresolution fix, and troubleshooting) are in docs/claude-desktop-config.md.
What stays local: your vault, the ChromaDB vector index, and the Neo4j graph never leave your machine. Claude Desktop only ever sees the specific passages Loom retrieves for a given question. It's the same data flow as any retrieval-augmented chat.
The 14 tools Claude gets:
Tool | What it does |
| Hybrid search (semantic + keyword + graph) with citations |
| Explore the knowledge graph around any concept |
| Find notes that are semantically related but never linked |
| Add a web URL to your vault |
| Vault statistics and top concepts |
| Write an entity or typed relationship into the graph |
| Remove a single relationship by edge id |
| Remove an entity and all its edges |
| Orphan notes, broken links, stale content, tag hygiene |
| Create a new markdown file in the vault |
| Edit a specific section of a note by heading |
| Read a specific section of a note by heading |
| Append content to an existing note |
| Trigger a background loop on demand (archaeology, audit, etc.) |
Prefer a browser to Claude Desktop? Loom also exposes an OpenAI-compatible API (loom_serve.py), and Open WebUI connects to it for a polished chat experience: citations, model switching, conversation history, no terminal.
Prerequisites: Loom installed (see above), Docker Desktop for Open WebUI.
One-time setup:
# 1. Start Open WebUI (one Docker command)
docker run -d -p 3030:8080 --add-host=host.docker.internal:host-gateway ^
-v open-webui:/app/backend/data --name open-webui --restart always ^
ghcr.io/open-webui/open-webui:main
# 2. Start the Loom API server
pip install fastapi uvicorn
python loom_serve.pyConnect Open WebUI to Loom (one-time, in the browser):
Admin Settings → Connections → + (OpenAI-compatible)
URL: http://host.docker.internal:11435 · Key: loom
Add model ID loom → Save
Daily use, just run:
python loom_serve.py
# then open http://localhost:3030 and pick the "loom" modelOn Windows, double-click Loom.bat in the install directory for one-click launch.
Every reply runs through the full retrieval pipeline (vector + graph + BM25 + HyDE + rerank) and cites the specific vault files behind each answer.
Retrieval (embedding, vector search, BM25, graph traversal, reranking) always runs
locally and in-process: sentence-transformers + ChromaDB, no external services
required for indexing or search. Only the final answer-generation step needs a model,
and you choose where that runs:
API mode (recommended). Set ANTHROPIC_API_KEY in a .env file at the repo root.
Loom uses Claude for synthesis: fast, high quality, no local GPU required. Because
embedding and retrieval are in-process, this is the lightest possible setup.
Local mode. Start Ollama and pull a chat model (ollama pull deepseek-r1:14b).
Synthesis runs fully on-device: slower and needs a capable GPU, but zero API cost and
fully air-gapped.
Most LLM-over-notes tools are stateless: they read your files fresh every conversation, re-derive connections on every query, and degrade as your vault grows past a few hundred notes.
Loom is stateful. A persistent vector index and knowledge graph accumulate over time. The relationships between your ideas are stored, traversable, and queryable, not re-derived on every request. When your vault hits 5,000 notes and you need to know what you forgot you knew two years ago, stateless tools can't help. Loom can.
What Loom does:
Ask your notes anything: semantic search + knowledge graph traversal with cited answers. Retrieval runs locally; synthesis uses Claude by default (or a local model)
See what you forgot: weekly reports find notes you read months ago that connect to what you're working on now (Knowledge Archaeology, live)
Track how your thinking evolved: monthly reports show how your understanding of a topic shifted over time (Temporal Reasoning, live)
Know where you're thin: weekly reports rank concepts where your coverage is shallow (Epistemic Audit, live)
Ingest everything automatically: drop PDFs, audio, and web URLs into one folder. Loom does the rest.
What Loom will never do:
Store your vault, index, or graph anywhere but your machine
Require a subscription or a vendor account
Stop working because a vendor got acquired
The only thing that ever leaves your machine is the handful of retrieved passages sent to Claude for synthesis. Run Ollama locally to keep even that on-device.
How Loom differs from agent-memory tools. Mem0, Graphiti, and Cognee store facts extracted from conversation histories. They're optimized for "remember what this user prefers across sessions." Loom is built for document corpora: thousands of notes, papers, transcripts, and web threads you've accumulated over years. The retrieval problem is different, the graph schema is different, and the use case is different. If you need your agent to remember a conversation, use Mem0. If you need to reason across your document library, that's Loom.
Loom | NotebookLM | Khoj | Smart Connections | InfraNodus | Mem0 | |
Surfaces forgotten connections | Yes (local) | No | No | Semantic only | Yes (cloud, €12+/mo) | No |
Knowledge graph | Full entity-relation | No | No | Semantic neighborhoods | Yes | Cloud only ($249/mo) |
Temporal reasoning | Yes (local) | No | No | No | No | No |
Knowledge gap detection | Yes (local) | No | No | No | Yes (cloud) | No |
Local-first (your data stays on device) | Yes | No (Google) | Self-host | Yes (plugin) | No (EU cloud) | No (cloud) |
Automated intake | Yes | Manual upload | Connectors | No | Import-based | No |
Works without Obsidian | Yes | Yes | No | No | Partial | Yes |
InfraNodus is the closest competitor: it also surfaces structural gaps and forgotten connections in a knowledge graph, and it ships as an Obsidian plugin. The difference is shape, not feature checkboxes. InfraNodus is cloud SaaS, single-purpose, and import-based: you upload a body of text, it analyzes that snapshot, you read the result. Loom is local, continuous, and integrated: it runs on your machine with no subscription, the graph grows every time you drop a file into intake, and the analysis lives inside a queryable second brain you can chat with. You don't export to Loom. Loom is where your notes live.
Feature | Status | |
⚡ | Semantic search: ask your notes anything, get cited answers | ✅ Live |
🕸️ | Knowledge graph: typed relationships; embedded FalkorDB (Mac/Linux) or Neo4j (Windows) | ✅ Live |
🎙️ | Whisper transcription: audio and video → indexed notes | ✅ Live |
📄 | PDF extraction: drop any PDF, it lands in your vault | ✅ Live |
🌐 | Web digest: Wikipedia, arXiv, HN, SEC, IRS, LessWrong | ✅ Live |
📚 | Topic packs: 46 curated corpora via | ✅ Live |
📦 | Loom Capture: standalone intake daemon, pipx installable | ✅ Live |
🖥️ | Web UI via Open WebUI: chat interface, no terminal needed | ✅ Live |
🏛️ | Knowledge Archaeology: weekly report of forgotten connections | ✅ Live (loop) |
⏱️ | Temporal Reasoning: monthly arc report of concept evolution | ✅ Live (loop) |
🧠 | Epistemic Audit: weekly knowledge gap analysis | ✅ Live (loop) |
🔍 | Vault health diagnostics: orphans, broken links, stale notes | ✅ Live |
⏰ | Temporal search lane: "last week" queries activate recency scoring | ✅ Live |
📝 | Note write tools: create, edit, append via MCP | ✅ Live |
🔄 | Real-time vault sync: file watcher re-indexes on save | ✅ Live |
🔁 | Loop runner: 6 scheduled background analyses | ✅ Live |
The one-click Windows installer is live (v0.2.1). On Mac/Linux, or prefer source? The pipx path below is the quickest, and Docker brings up the full stack. Works on Windows, Mac, and Linux.
Prefer to inspect the installer before running it? See Installer Trust — exactly what it touches, how to read it yourself, and how to pin to a release.
Quickest: install from PyPI
pip install loom-pkm
loom init
loom chatLoom is on PyPI as loom-pkm — no clone needed. pipx install loom-pkm works too if you prefer an isolated install. All the source-based paths below still work.
1. Claude Desktop (MCP): the recommended way to use Loom
Install Loom from source (the pipx step below is fine), then wire it into Claude Desktop and ask your vault questions right from the chat. Full walkthrough: Connect to Claude Desktop.
git clone https://github.com/KlossKarl/loom
cd loom
LOOM_EMBEDDED=true pipx install . # or: pip install -e .
loom init # creates config.yaml (required before connecting)
# then add loom to claude_desktop_config.json (see the section linked above)2. pipx: the default first run (no Neo4j, no Ollama, no server)
pipx install .
loom init
loom chatOn Mac/Linux (Python ≥ 3.12) this includes the embedded FalkorDB graph
backend, so full graph features — typed relationships, graph search,
archaeology — work out of the box with zero extra services. On Windows
(or older Pythons) the same install runs in vector-only embedded mode, and
Neo4j is the optional graph upgrade — nothing to migrate, your index carries
over. Backend selection is automatic (second_brain.graph_backend: auto).
3. Docker: full graph stack (Neo4j + Ollama), no manual dependency setup
Want the optional full graph features from day one? Docker brings up the vector store, Neo4j graph database, and local LLM with no manual Python/Neo4j/Ollama install:
git clone https://github.com/KlossKarl/loom
cd loom
# 1. Configure: copy the env template and set your vault path
cp .env.example .env
# then edit .env: LOOM_VAULT_PATH is required (point it at your notes folder)
# 2. Bring up the services (Neo4j + Ollama + Loom)
# Ollama auto-detects the accelerator (Metal on Apple Silicon, else CPU);
# no GPU config needed. Nvidia homelab users can add passthrough via a
# docker-compose.nvidia.yml override.
docker compose up -ddocker compose up starts the services but does not index or chat on its
own. The Loom container idles until you run commands against it:
docker compose run --rm loom python src/second_brain/second_brain.py --index
docker compose run --rm loom python src/second_brain/second_brain.py --chat⚠️ Never run
cat .envin a shared screen, terminal recording, or chat session. Your.envfile contains your Anthropic API key. If exposed, rotate it immediately at console.anthropic.com → API Keys. To safely inspect your config without printing secrets:grep -v API_KEY .env
4. Development install (from source)
git clone https://github.com/KlossKarl/loom
cd loom
pip install -e .
LOOM_EMBEDDED=true loom init
loom chatDrop files into intake/, then ask your notes anything.
First graph index is slow: the --graph-index pass uses your local LLM (or Claude Haiku) to extract entities from every file. On a mid-range GPU, expect it to run overnight. Vector index is fast (~10 minutes). For a free, fast first pass, --quick-graph-index uses GLiNER v2.1 locally. See below.
Tested on Windows: Loom uses Path() throughout and should work on Mac/Linux, but it's only been tested on Windows. PRs welcome.
Graph backends: on Mac/Linux the knowledge graph runs on an embedded FalkorDB backend by default (installs with Loom, no server). On Windows, Neo4j is the graph backend; without it Loom runs vector-only. Force a choice with second_brain.graph_backend: falkor|neo4j, or set LOOM_EMBEDDED=true for vector-only mode anywhere.
Entity extraction: local and free, or Claude Haiku. The knowledge graph is
built by --graph-index (Claude Haiku via the Anthropic API when a key is set,
falling back to your local chat_model) or by --quick-graph-index, which uses
GLiNER v2.1 (urchade/gliner_multi-v2.1),
a 209M-param local NER model with zero API cost that runs entirely on your
machine. See docs/usage.md for
the trade-offs.
Loom ships with a desktop control panel (src/whisper/intake_tray.py):
Intake tab: drag-and-drop files + YouTube URL queue
Search tab: vector and graph search against your vault
Chat tab: persistent local LLM conversation
Status tab: vault stats, watcher status, index runner
Runs in the system tray. Start it with:
python src/whisper/intake_tray.pyThe Windows installer launches this automatically on first run.
Drop a file into the intake folder. It routes itself.
lecture.mp3 -> Whisper transcription -> vault -> indexed
paper.pdf -> PDF to markdown -> vault -> indexed
thread.txt -> Web digest -> structured note -> vault -> indexed
https://...url -> Same as above
note.md -> Copied directly to vault -> indexedThen ask questions:
> what did the stanford cs229 lecture say about attention mechanisms?
> compare the risk frameworks across my last 5 papers
> what connects OODA loop to predictive coding?
> find everything I've read about CLO structuresRetrieves from ChromaDB (vector search), traverses Neo4j (knowledge graph), and generates the answer with Claude by default (or a local LLM via Ollama). Indexing, retrieval, and your data stay on your hardware.
You've been reading about retrieval-augmented generation for months. Papers, blog posts, podcast transcripts, HN threads. All dropped into intake/ as they came in. You never organized them.
Six months later, you need to write a synthesis. You type:
loom chat
> What are the main approaches to RAG and how do they compare?Loom searches the vector index, walks the knowledge graph, and returns an answer citing 14 of your notes across 8 sources, including a podcast transcript from January you completely forgot about, and a connection between two papers you never would have made manually.
The answer includes citations back to the exact vault files. You click through, verify, and start writing. The system got smarter while you weren't looking, because the graph accumulated relationships every time you fed it something new.
That's what stateful retrieval means. A stateless tool would have started from scratch.
intake/ <- drop anything here
|
src/whisper/intake_watcher.py <- watches folder, routes by file type
|
+--------------------------------------------------+
| transcribe.py pdf_to_md.py web_digest.py |
| Whisper pymupdf Claude Code |
+--------------------------------------------------+
|
Obsidian Vault <- all content lands here as markdown
|
src/second_brain/second_brain.py --index <- chunks + embeds into ChromaDB
src/second_brain/second_brain.py --graph-index <- extracts entities/relationships into Neo4j
|
+--> src/second_brain/second_brain.py --chat <- CLI: hybrid retrieval (vector + graph + HyDE + rerank)
|
+--> loom_serve.py <- OpenAI-compatible HTTP API
|
+--> Open WebUI (browser) <- full chat UI with citations
+--> Continue.dev / any OpenAI clientgraph LR
A[📁 intake/] --> B[Folder Watcher]
C[🎙️ Audio] --> D[Whisper]
E[📄 PDF] --> F[PyMuPDF]
G[🌐 Web URL] --> H[Web Digest]
B --> I[(ChromaDB\nVector Index)]
D --> I
F --> I
H --> I
I --> J[Neo4j\nKnowledge Graph]
I --> K[💬 loom chat]
J --> K
I --> M[loom_serve.py\nOpenAI-compatible API]
J --> M
M --> N[🖥️ Open WebUI]
K --> L[📝 Obsidian Vault]For details on the knowledge graph schema, see docs/graph_schema.md.
Loom is opinionated about graph schema and entity resolution. It trades flexibility for long-term coherence: every relationship is typed, every entity is resolved, and the graph gets smarter the more you feed it.
A few specific things, since "local-first RAG" is a crowded space.
Constrained typed relationships, not unconstrained predicate generation. The Neo4j schema uses a fixed set of relationship types: CITES, INFLUENCES, EXTENDS, CONTRASTS_WITH, UNCERTAIN_SAME_AS, UNTYPED_RELATION, CO_OCCURS_WITH, and REFERS_TO. Anything the LLM tries to emit outside that set is rewritten to UNTYPED_RELATION with the original predicate preserved on r.raw_type. This is more restrictive than letting the model invent edge types, but the graph stays coherent at scale instead of fragmenting into thousands of one-off predicate names. The validation happens at the graph write layer, not just in the prompt.
Evidence-backed graph extraction. Every semantic edge (and every MENTIONS link from a chunk to an entity) carries an evidence_span (a ≤200-char verbatim quote from the source chunk) and an edge_confidence score. Every :Entity node carries an extraction_confidence (max of all scores ever seen for it). You can ask "where did this come from?" and get the actual line of text the LLM was looking at when it made the claim. Most graph-RAG tools throw this provenance away the moment extraction finishes.
Entity resolution with canonical keys + aliases. "PAC-learning", "PAC learning", and "pac learning" all collapse to the same canonical key in the graph (lowercase, hyphens → spaces, stripped possessives/articles/accents, conservative plural strip), with the original surface forms preserved as Alias nodes linked via HAS_ALIAS. This handles the entity dedup problem most LLM-extracted graphs ignore. Without it, the graph fills with near-duplicate nodes and cross-document traversal breaks down.
Wikilink-aware graph. Obsidian [[wikilinks]] between vault notes are extracted and written as Document→Document REFERS_TO edges: user-curated structure, no LLM call. The graph respects the connections you drew by hand, not just the ones a model inferred.
Adaptive query routing, not blind hybrid retrieval. Most personal RAG tools run the same retrieval pipeline regardless of query type. This one classifies the query first (semantic, relational, or hybrid), routes to the appropriate store (ChromaDB, Neo4j, or both), then runs a sufficiency check and loops up to 3 times if context is insufficient. The router falls back to vector if graph comes up empty, or expands into graph if vector results don't answer the question. The route taken is logged so you can see how the system is thinking.
Cross-document queries vector search cannot answer. Because entities are shared nodes across documents, you can traverse Document -> Chunk -> Entity <- Chunk <- Document to find pairs of documents that both reference the same concept. That's a single Cypher traversal. Pure vector RAG cannot answer this structurally no matter how big the context window gets.
Benchmarks: Recall@10 0.947 · MRR@10 0.861 (hybrid + rerank, measured on an NVIDIA RTX 4070 Ti with CUDA — Mac/MPS and CPU runs rerank slower and may score slightly differently) · full methodology →
Note: most AI memory benchmarks test conversation recall — a different task from document retrieval.
This list is for source installs. The Windows installer (v0.2.1, live) bundles Python and handles setup automatically.
Python 3.10+
Ollama - local LLM inference for chat. Pull a model based on your hardware:
Profile | VRAM | Chat model | Quality |
Budget | 4-8GB |
| Good for chat, basic graph |
Mid (default) | 8-16GB |
| Solid all-around |
High | 16-24GB |
| Better local graph extraction |
Workstation | 48GB+ |
| Near-frontier quality |
Embeddings run in-process via sentence-transformers (current default mxbai-embed-large). No separate Ollama pull required. For new installs we recommend qwen3-embedding, which leads current retrieval benchmarks; mxbai-embed-large remains a solid fallback.
Graph extraction defaults to Claude Haiku via the Anthropic API when anthropic.api_key is set in config.yaml. This is the recommended path: it's faster, more accurate, has prompt caching (~5× cost reduction), and costs about $5 for a full 18K-chunk index. If no API key is configured, Loom falls back to your local chat_model for extraction.
Neo4j Desktop (optional; Windows graph backend) - on Mac/Linux the knowledge graph uses the embedded FalkorDB backend instead (installs with Loom, no server). Install Neo4j on Windows when you want the knowledge graph (see below)
Obsidian - vault is just a folder of markdown, Obsidian is optional but recommended
Claude Code - used for free-tier web digest processing (optional but recommended)
Decent hardware. 16GB RAM minimum. A GPU with 8GB+ VRAM makes graph indexing significantly faster.
If you only want the intake half (automatic Whisper transcription, PDF → markdown, web/HN/Reddit/Wikipedia digests, all dropping into any folder you point at), there's a standalone product:
pipx install loom-capture
loom-capture init
loom-capture watch→ loom-capture/. Free, MIT, no API key, no vector DB, no graph. Works with Obsidian, Logseq, or any folder of markdown files.
Morning: you listen to a podcast and drop the mp3 into your vault. Capture transcribes it via Whisper and files it as markdown.
Afternoon: you paste three URLs into a text file in intake/: an arXiv paper, a Wikipedia article, and an HN thread. Capture digests all three into clean markdown notes.
Evening: you open Obsidian and everything is there, searchable, formatted, filed. You did zero manual work.
The loom init wizard handles this for you, but if you prefer to set things up by hand:
cp config.template.yaml config.yaml
# edit config.yaml with your pathsNeo4j setup (optional upgrade for full graph features — the default embedded mode doesn't need it):
Install Neo4j Desktop
Create a new Project, add a Local DBMS
Set a password, start the instance
Put the password in config.yaml under second_brain.neo4j_password
paths:
obsidian_vault: C:\Users\you\Documents\Obsidian Vault
chroma_dir: C:\Users\you\Documents\second_brain_db
second_brain:
vaults:
- C:\Users\you\Documents\Obsidian Vault
embed_model: mxbai-embed-large
chat_model: deepseek-r1:14b
neo4j_uri: neo4j://127.0.0.1:7687
neo4j_password: yourpassword
# customize entity types for your domain
entity_types:
- Person
- Concept
- Method
- Paper
- Organization
- Dataset
intake:
folder: C:\Users\you\Documents\loom\intake
auto_index: true
web_digest_free: true # true = Claude Code (free), false = Anthropic APIThe fastest path is the intake watcher. Run it once and drop files into
intake/; they get transcribed/digested and indexed automatically:
python src/whisper/intake_watcher.pyThe full command reference covers indexing, graph building (LLM and GLiNER), chat, web digests, transcription, research-source batches, and the in-chat retrieval toggles. See docs/usage.md.
loom ships with 46 pre-built semantic corpora, curated knowledge bases (AI, quant finance, mathematics, law, philosophy, and more) you can ingest in a few hours to start with a connected, queryable foundation instead of an empty vault.
List and install them straight from the CLI:
loom pack list # show all 46 packs with URL and install counts
loom pack install ai_agents # ingest a pack via the web-digest pipeline, then indexInstalls are resumable, so a failed URL or an interrupted run picks up where it left off.
→ See docs/topic-packs.md for the full list and usage.
Tested on Windows. Paths use Path() throughout so it should work on Mac/Linux, but that hasn't been tested. PRs welcome.
Graph indexing is slow on large vaults: roughly 0.5 seconds per chunk on the current default hardware profile. For a vault with thousands of files this means running overnight. Batched UNWIND writes (Phase 2) will cut this significantly on multi-core machines.
No web UI. Web UI is now live via loom_serve.py + Open WebUI. See Quick Start: UI Mode.
P0: Onboarding (shipped)
docker-compose.yml: one command full stack
LOOM_EMBEDDED=true: zero-dependency first run
pipx installable: pipx install .
loom init wizard: OS-aware path detection, auto-configures Claude Desktop
One-click Windows installer (v0.2.1): bundles Python, no Neo4j required
loom pack list / loom pack install: 46 curated topic packs from the CLI
P1: Loom Capture (shipped)
Standalone intake pipeline: pipx install loom-capture
Three commands: loom-capture init, watch, digest
Extraction Quality: Phase 0 + Phase 1 (shipped 2026-05-20)
Claude Haiku as default graph extraction model (with prompt caching, ~5× cost reduction)
Evidence spans + confidence scores on every entity and every semantic/MENTIONS edge
Typed exception handling + quality metrics summary at end of every --graph-index run
UNCERTAIN_SAME_AS / UNTYPED_RELATION split (retires POSSIBLY_SAME_AS)
Hallucination guard: entity names validated against source text
Obsidian [[wikilinks]] → Document→Document REFERS_TO edges
In-process sentence-transformers embedding (eliminates the old Ollama HTTP 500s under load)
BM25 disk cache (avoids cold rebuild every session)
ingested_at on every graph node: temporal foundation
Extraction Quality: Phase 2 (pending, new hardware)
Batched UNWIND Neo4j writes: utilises full CPU core count
Reranker upgrade to bge-reranker-v2-m3 (Recall@10 0.853 → 0.947 on CUDA, now on by default)
Degree cap on graph traversal (hub-node protection)
Retrieval deduplication
First full clean graph index run on the new PC
Performance
CUDA-accelerated reranking (CUDA PyTorch wheel; reranked queries now ~350ms on an RTX 4070 Ti — CPU fallback still works, just slower)
P2: Next Generation
Knowledge Archaeology: weekly loop surfaces forgotten notes ✅ shipped
Epistemic Audit: weekly knowledge gap report ✅ shipped
Temporal Reasoning: monthly arc report of how your thinking evolved ✅ shipped
loom_serve.py: OpenAI-compatible HTTP API (Open WebUI, Continue.dev) ✅
Argument layer: extract claims/evidence/debate structure into the graph
Graph visualization UI
Mac/Linux testing and fixes
Browser extension for web digest
Infrastructure
Embedded graph backend (Mac/Linux): FalkorDBLite (falkordblite) ships as the default graph backend — pip-only, no server, no JVM. The 2026-06 FalkorDB spike failed because the hyphenated package didn't exist; falkordblite does, and passed the full compat + parity gates (FALKORDBLITE_SPIKE_RESULTS.md).
Embedded graph backend (Windows): falkordblite has no win32 support, so Windows still needs Neo4j for graph features. SQLite-graph spike spec remains the candidate path to close this last gap.
loom/
├── src/ # all Python modules
│ ├── whisper/ # audio/video to markdown + intake watcher/tray
│ ├── second_brain/ # core: index, chat, graph
│ └── web_digest/ # all ingestion scripts + topic files
├── experiments/ # exploratory scripts (lightrag_test, etc.)
├── docs/ # guides, ADRs, usage, topic packs
├── config.template.yaml # starting point, copy to config.yaml
└── config.yaml # your config (gitignored)If Loom is useful to you, a ⭐ on GitHub helps more people find it.
Questions or ideas? Open an issue.
The installer uses CPU-only PyTorch by default (~200 MB). For GPU-accelerated embeddings, install CUDA torch manually:
pip install torch --index-url https://download.pytorch.org/whl/cu121Note: Loom's LLM inference (chat, analysis, graph extraction) runs through Ollama, which manages GPU access independently. CUDA torch only affects the embedding model (sentence-transformers).
To compare embedding models on your actual vault content:
python experiments/embedding_benchmark.py --sample 500Samples chunks from your existing ChromaDB collection, re-embeds them with each candidate model, runs a set of queries against each, and reports latency + retrieval results. Defaults to comparing mxbai-embed-large, nomic-embed-text-v1.5, and bge-m3. Results saved to experiments/embedding_benchmark_results.json.
Loom is a solo project but issues and PRs are welcome.
Bug reports: open a GitHub issue with steps to reproduce
Feature requests: check the roadmap first, then open an issue
Pull requests: keep them focused. One thing per PR
MIT
Write a correction into the knowledge graph. With only 'subject', declares/upserts a single entity. With 'subject', 'relation', and 'object', asserts a typed relationship between two entities (creating either endpoint if missing). Valid relations: CITES, CONTRASTS_WITH, EXTENDS, INFLUENCES, UNCERTAIN_SAME_AS, UNTYPED_RELATION. Manual writes are tagged source='manual_mcp'. Use for surgical fixes, not bulk import.
| Name | Required | Description | Default |
|---|---|---|---|
| object | No | Target entity name. Omit to just declare 'subject'. | |
| subject | Yes | Entity name (the source entity). | |
| evidence | No | Optional ≤200-char justification stored on the edge. | |
| relation | No | Relationship type. Required only when 'object' is given. | |
| confidence | No | Confidence 0.0–1.0 (default 1.0 for human-asserted facts). | |
| object_type | No | Entity type for object (default Concept). | Concept |
| subject_type | No | Entity type for subject (default Concept). | Concept |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, description fully discloses upsert semantics ('declares/upserts'), confidence range, evidence length limit, and the source tagging. It does not cover potential side effects like overwriting existing edges or error conditions, but covers core behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Six sentences, no redundant words. Information is front-loaded: purpose first, then modes, relation list, tagging note, and usage advice. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all main use cases and parameter combinations. Missing output schema but not critical for a write tool. Lacks explicit error handling or idempotency statement, but still adequate for a focused tool with 7 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds meaning by explaining the dual-mode logic (entity vs. relationship), listing valid relations, and noting the default confidence rationale for human-asserted facts. Evidence length constraint is also clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool writes corrections into a knowledge graph, with two distinct modes (entity declaration or relationship assertion). It differentiates itself from siblings like delete_edge or forget_entity by focusing on adding facts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit advice: 'Use for surgical fixes, not bulk import.' Valid relations are listed, and the manual-write tagging is noted. However, it does not explicitly contrast with alternatives like ingest_url for bulk imports.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append content to the end of an existing vault note (fuzzy filename match). Simpler than edit_section — no heading needed.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Filename or vault-relative path. | |
| content | Yes | Content to append. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the fuzzy filename matching behavior and the append operation (non-destructive). However, it does not mention what happens if the file is not found, multiple matches, or whether the note is automatically created (it says 'existing vault note', implying it must exist).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two sentences, front-loading the verb and resource. Every word adds value, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no output schema and only two parameters, the description covers the basics. It could be more complete by specifying that the note must already exist, how fuzzy matching works, or error handling. But given the simplicity, it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with adequate descriptions for both parameters. The description adds context about fuzzy matching for the 'file' parameter, but does not significantly enhance understanding beyond the schema for 'content'. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('append'), the resource ('existing vault note'), and the method ('fuzzy filename match'). It also distinguishes from the sibling tool 'edit_section' by noting that no heading is needed, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear comparison to 'edit_section' ('Simpler than edit_section — no heading needed'), guiding when to use this tool over the sibling. However, it does not explicitly state when not to use it or mention prerequisites like the note must already exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new markdown note in the vault. Refuses to overwrite existing files. Adds YAML frontmatter (source: mcp_create, plus any tags). Smart-write pipeline: suggests existing tags for near-duplicates, discovers wikilink candidates among existing filenames, and — when 'folder' is omitted — places the note in the folder of the most semantically similar existing note.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Optional tags for frontmatter. | |
| title | Yes | Note title (becomes the filename). | |
| folder | No | Vault-relative folder. Omit for automatic semantic placement. | |
| content | Yes | Markdown body of the note. | |
| auto_wikilink | No | Auto-insert [[wikilinks]] for discovered matches (default false → suggest only). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully informs the agent about key behaviors: it refuses to overwrite, adds YAML frontmatter, and has a smart-write pipeline for suggestions and automatic folder placement. This provides thorough transparency without contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core purpose, and each sentence adds essential information without redundancy. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema or annotations, the description covers the tool's main function, refusal behavior, frontmatter addition, and smart-write pipeline details for all parameters. It provides sufficient context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the smart-write pipeline (e.g., auto_wikilink defaults to suggestion-only, folder omission triggers semantic placement). This extra context justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new markdown note in the vault' which is a specific verb and resource. It implies differentiation from siblings like append_to_note or edit_section by focusing on creation, but does not explicitly distinguish itself, so a 4 is appropriate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating new notes and mentions refusal to overwrite, but it does not explicitly state when to use this tool versus alternatives like append_to_note. Usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a single relationship from the knowledge graph by its edge_id. Get edge_ids from get_entity_neighbors. Deletes only the edge — both entities remain.
| Name | Required | Description | Default |
|---|---|---|---|
| edge_id | Yes | The elementId of the edge to delete. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that the delete targets only the edge and preserves entities, but does not address permissions, reversibility, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, focused sentences. No extraneous information. Front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (1 parameter, no output schema), the description covers what the tool does, how to obtain the input, and the outcome (edge removed, entities intact). Complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameter description in schema already explains edge_id as the elementId to delete. Description does not add significant new meaning, but schema coverage is 100%, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Remove a single relationship'), the resource ('knowledge graph'), and the identifier ('by its edge_id'). It distinguishes from sibling tools like forget_entity by specifying that both entities remain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to get edge_ids from get_entity_neighbors, providing clear preparation steps. Does not list scenarios to avoid, but the guidance is sufficient for proper use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit one section of an existing note, located by heading (any level, fuzzy filename match). mode = replace | prepend | append. All content outside the targeted section is preserved. Returns the edited section for confirmation.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Filename or vault-relative path. | |
| mode | No | How to apply content. | replace |
| content | Yes | The content to write into the section. | |
| heading | Yes | The heading whose section to edit. | |
| auto_wikilink | No | Auto-insert [[wikilinks]] for discovered matches. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully bears the burden of behavioral disclosure. It explains the three modes (replace, prepend, append) and states that non-targeted content is preserved. It also indicates the return of the edited section for confirmation. However, it does not specify behavior when the heading is not found or error handling, but overall it provides a clear behavioral model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with the first sentence defining the action and location, and the second explaining the mode and preservation behavior. Every sentence is informative and there is no redundancy. It is appropriately concise and structured for quick reading.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no output schema, and a moderate complexity (edit with three modes, fuzzy matching), the description covers the primary behavior. However, it could be more complete by explaining what happens if the heading is not found or how the fuzzy match works. The return value is mentioned ('Returns the edited section for confirmation'), which adds completeness. Overall sufficient for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all parameters with descriptions (100% coverage). The description adds value by explaining that the heading lookup uses fuzzy filename matching and applies to any level, which is not in the schema. The mode options are already in the schema as an enum. The description adds some context but does not fully compensate for the schema's existing detail; however, it enhances understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool edits a section of an existing note identified by heading, with fuzzy filename matching. It specifies the action (edit one section) and the resource (existing note, located by heading), distinguishing it from siblings like append_to_note or read_section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions that all content outside the targeted section is preserved, implying it is for surgical edits. However, it does not explicitly state when to use this tool versus alternatives like append_to_note for appending to the end of the note or read_section for reading. The context from sibling tool names provides implicit differentiation, but explicit guidance would be better.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove an entity and ALL of its relationships from the knowledge graph (and any aliases left orphaned). Matches by exact canonical key — surgical, not fuzzy. Destructive and not reversible without re-indexing.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_name | Yes | The entity to delete. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description discloses key traits: removes all relationships, handles orphaned aliases, exact match, irreversible. Could mention re-indexing implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with critical information front-loaded; no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple one-param tool with no output schema; covers deletion scope and constraints but lacks return value hint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description adds exact canonical key matching context beyond schema's description of 'The entity to delete', which has 100% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Remove' with specific resource 'entity and ALL of its relationships'; distinguishes from sibling tools like delete_edge.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States exact-match binding and destructive nature, implying when to use, but lacks explicit when-not or alternative tool comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Surface forgotten connections in your vault. Finds notes and concepts that are semantically related but never linked, and clusters of knowledge you may have forgotten about.
| Name | Required | Description | Default |
|---|---|---|---|
| focus_topic | No | Optional — narrow the report to a topic area. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only says it 'surfaces' connections. It does not disclose whether this is read-only, what the output format is, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with front-loaded purpose. Could be more technical but avoids excessive fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description partially explains what the report finds but omits details like output format, whether it modifies data, or how to interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage for the single optional parameter, which is described as narrowing to a topic area. The tool description adds no new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it finds semantically related but unlinked notes and forgotten knowledge clusters. This is a specific verb-resource pairing, distinguishing it from siblings like 'search_vault' or 'get_entity_neighbors', though the language is slightly poetic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use versus alternatives. Only implied context of discovering hidden connections, without contrasting with similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Given a concept or entity name, find everything connected to it in the knowledge graph. Returns related entities and the typed relationships between them (CITES, INFLUENCES, EXTENDS, CONTRASTS_WITH, etc) with the evidence spans that justify each edge.
| Name | Required | Description | Default |
|---|---|---|---|
| max_hops | No | How many hops out to traverse (default 2, max 3). | |
| entity_name | Yes | Concept or entity to explore. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that the tool returns related entities, typed relationships, and evidence spans, which implies read-only behavior. However, it does not mention any authentication requirements or rate limits, but the tool appears safe.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that conveys all necessary information without redundancy. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains that the tool returns related entities, typed relationships, and evidence spans. It covers the tool's core functionality and return values, making it complete for an agent to understand what it does.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds limited extra meaning. The mention of 'CITES, INFLUENCES, etc.' provides context but does not explain parameter syntax or constraints beyond what the schema already provides (e.g., max_hops bounds).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('find everything connected'), resource ('knowledge graph'), and scope ('given a concept or entity name'). It also lists the return format (related entities and typed relationships with evidence spans), distinguishing it from sibling tools like search_vault which likely perform full-text search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (exploring connections from a starting entity) but does not explicitly state when not to use or mention alternatives. Sibling tools like search_vault could be used for different queries, but no guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Diagnose vault hygiene: orphan notes (no wikilinks in or out), broken wikilinks (point to missing files), stale notes (old and weakly connected), and tag issues (likely typos, inconsistent casing). Works in vector-only mode; uses the graph for connectivity when Neo4j is available.
| Name | Required | Description | Default |
|---|---|---|---|
| stale_days | No | Age threshold in days for stale-note detection (default 90). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry full burden. It discloses detection capabilities and mode dependency, but does not mention read-only nature, side effects, or authentication requirements. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. Efficiently communicates purpose and operational details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema provided and description does not explain the return structure or format. For a diagnostic tool, knowing the output shape is important for agent interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter already described in the schema. The description adds no additional meaning or constraints beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool diagnoses vault hygiene, listing specific issues (orphan notes, broken wikilinks, stale notes, tag issues). It distinguishes from siblings like 'get_vault_stats' and 'get_archaeology_report' by focusing on health diagnostics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides operational context: works in vector-only mode and uses graph when Neo4j is available. It does not explicitly state when to use alternatives, but the description implies its specific use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get statistics about your knowledge vault: total documents, chunks indexed, entity count, and top concepts by frequency.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It adequately describes the output but does not explicitly state that it is read-only or discuss any potential costs, rate limits, or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence of 15 words that efficiently conveys the tool's purpose without extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple and the description lists key statistics, it lacks differentiation from similar tools like get_archaeology_report. No output schema exists, so the description could provide more detail on formatting or structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100%. The description adds value by listing the output fields, which is helpful for understanding the expected response.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool retrieves statistics about the knowledge vault, listing specific metrics (total documents, chunks, entities, top concepts). This clearly distinguishes it from sibling tools like search_vault or add_fact, which perform different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as get_archaeology_report or get_vault_health. The description does not provide context for selection or exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a web URL to your vault. Loom will fetch, parse, and index it. Supports general web pages, arXiv papers, Wikipedia articles, HN threads, and more.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The URL to ingest. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool fetches, parses, and indexes the URL, and lists supported content types. However, it omits potential side effects like rate limits, storage impact, or what happens with invalid URLs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that front-load the main action ('Add a web URL to your vault') and then provide context. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple ingestion tool, the description covers the core action. However, it does not mention return values or error handling. With no output schema, the agent lacks information on what to expect after calling the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add extra meaning beyond the schema; it simply restates 'URL'. No format or syntax details are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Add' and resource 'web URL to your vault', and distinguishes from sibling tools like add_fact or create_note by focusing on URL ingestion. The description also elaborates on what Loom does with the URL.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like add_fact or create_note. The description implies general web URLs but does not tell the agent when not to use it or provide criteria for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read just one section of a note (from a heading to the next heading of equal or higher level). Fuzzy filename match. Lower token cost than reading the whole document.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Filename or vault-relative path. | |
| heading | Yes | The heading whose section to return. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses fuzzy filename matching and lower token cost, but does not mention safety (read-only), error handling (e.g., missing heading), or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no extraneous words. The first sentence states the core action with scope, the second adds benefits. Perfectly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with two parameters and no output schema, the description covers action, scope, file matching behavior, and cost efficiency. Could mention that the result is plain text or markdown, but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds 'fuzzy filename match' for the file parameter, slightly augmenting the schema. No additional semantic value for the heading parameter beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the tool's function: reading one section of a note from a heading to the next heading of equal or higher level. It differentiates from sibling tools like read_full_note (implied) and edit_section by focusing on partial reading.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states a key benefit ('lower token cost than reading the whole document'), guiding toward usage when efficiency matters. However, it lacks explicit guidance on when to use alternatives like edit_section or search_vault.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trigger a Loom background loop on demand. 'vault_health' writes a health report to the vault; 'stale_check' writes a stale-notes review; 'index_freshness' re-indexes files changed since the last index pass; 'all' runs every loop that is due. Reports are written into the vault's 'Loom Reports' folder.
| Name | Required | Description | Default |
|---|---|---|---|
| loop | Yes | Which loop to run. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full transparency burden. It discloses that reports are written to the 'Loom Reports' folder, but does not mention side effects, permissions, or whether loops are asynchronous. Adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the main action, then enumerates loop variants. No redundant information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter, no output schema, and no annotations, the description is mostly complete. It covers all loop variants and output location. Missing info: whether loops run synchronously or asynchronously, or any prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a described enum. The description adds significant meaning by explaining the outcome of each enum value (e.g., 'writes a health report', 're-indexes files'). This goes beyond the simple schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Trigger') and resource ('Loom background loop') and clearly lists each loop variant with its purpose. It distinguishes from siblings which are unrelated (notes, vault stats, etc.).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each loop (health report, stale review, re-indexing, all due) and implies that the agent should choose based on task. It lacks explicit 'when not to use' or alternatives, but siblings are very different so guidance is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search your personal knowledge vault using hybrid retrieval (semantic + keyword + knowledge graph). Returns cited passages from your notes.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | What to search for. | |
| max_results | No | Maximum passages to return (default 10). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It discloses the retrieval method (hybrid) and output format (cited passages). It doesn't explicitly state it's read-only, but 'returns' implies no side effects. Could be improved by noting no modifications, but adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 18 words, efficiently conveys purpose, method, and output. No wasted words or redundancy. Front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (search with two parameters, no output schema needed), the description fully covers what the agent needs: what it does, how it works, and what it returns. No gaps for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters ('What to search for' and max results). The description adds context about hybrid retrieval and output but adds no new meaning to the parameters beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb ('Search') and resource ('personal knowledge vault'), specifies hybrid retrieval method (semantic + keyword + knowledge graph), and mentions output (cited passages). Distinguishes from siblings like read_section (reads specific section) and get_entity_neighbors (graph traversal).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates that this tool is for searching the vault, but does not explicitly state when to use it versus alternatives like read_section or get_entity_neighbors. No when-not-to-use or specific filtering guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.2.1add_factappend_to_notecreate_notedelete_edgeedit_sectionforget_entityget_archaeology_reportget_entity_neighborsget_vault_healthget_vault_statsingest_urlread_sectionrun_loopsearch_vaultEach tool has a distinct purpose: note creation vs editing vs reading, graph operations (add facts, delete edges, forget entities), vault health/stats, search, import, and background loops. No two tools do the same thing.
All tool names follow a consistent verb_noun pattern in snake_case, with verbs like add, append, create, delete, edit, forget, get, ingest, read, run, and search. The naming is uniform and predictable.
14 tools is well-scoped for a knowledge vault server. Each tool covers a distinct operation without overwhelming the user. The count is appropriate for the domain's complexity.
The tool surface covers most essential operations: note CRUD (except delete), graph management, health checks, import, and background loops. Minor gaps like missing note deletion or rename are not critical for core functionality.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
Self-hosted AI-native knowledge workspace with hybrid search, GraphRAG, and MCP.
Persistent, portable memory for AI assistants — your private memory graph, from any MCP client.
Token-efficient MCP memory for Markdown vaults. Tiered search, GraphRAG, AI memories.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/KlossKarl/loom'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
