A persistent symbol index for AI coding agents. Agents find functions instantly. Agents write summaries as they work. The cache gets richer every session — zero LLM cost from Loom's side.
What Loom is
Loom indexes your codebase into a local SQLite database using tree-sitter. It extracts functions, classes, methods, and call relationships across all languages. Agents query it to skip file exploration and read only what they need. When an agent understands a function, it writes a summary back — the next agent gets it for free.
Persistent code graph for AI agents. Tree-sitter → SQLite → MCP. Agents store understanding once, skip re-reads forever. 51–1500x fewer tokens.
ดาว
4
เครื่องมือ
—
อัปไทม์
—
Core loop:
loom analyze . # tree-sitter indexes all symbols → ~/.loom/projects/myrepo.db
search_code("login") # instant: {name, path, line, summary, signature}
search_code("tag:auth login") # tag-filtered search — AND semantics
get_context(node_id) # full picture: summary + callers + callees + complexity + tags
store_understanding(id, s) # cache what you learned → returned on future searches
No Docker. No embeddings. No LLM calls from Loom. Pure tree-sitter + SQLite.
Why it matters
Every Claude Code / Cursor / Codex session starts by re-exploring the codebase: reading CLAUDE.md, grepping for functions, re-discovering structure. Loom eliminates that.
Full context packet: summary, signature, callers, callees, staleness. Use brief=True for metadata-only. Use callers_limit=0 / callees_limit=0 to skip traversal.
get_blast_radius(node_id, depth)
Transitive callers via recursive CTE — each result includes summary
get_neighbors(node_id, depth, limit)
All edges, both directions — each result includes summary
get_community(community_id, limit)
All members of a community cluster — each result includes summary
shortest_path(from_id, to_id)
Shortest directed path on CALLS subgraph — each hop includes summary
v0.6.1 note: The 4-part {kind}:{repo}:{path}:{symbol} format is planned for a future phase. Current IDs remain 3-part.
Agent workflow
# Session start — register first, then orient
start_session(agent_id="claude-code") # store returned session_id
# Or if returning:
get_delta(previous_session_id="<id>") # only what changed since last time
resource = read("loom://primer") # orient: modules, hot functions, coverage
suggest_questions() # dead code, bridge nodes, missing summaries
# Finding code
results = search_code("validate token") # summary + signature included
# If results[0].summary → read summary, skip file
# Before reading any file
ctx = get_context("function:src/auth.py:validate_token")
# Returns callers, callees, summary, staleness — often enough to reason without reading
# After understanding a function
store_understanding(
node_id="function:src/auth.py:validate_token",
summary="Validates JWT tokens, returns False if expired or signature invalid."
)
# Returns {"ok": true, "skipped": false} — written
# Returns {"ok": true, "skipped": true} — already fresh, no re-write needed
How summaries work
Auto-summaries:loom analyze fills summaries from static metadata (params, return type, decorators) via tree-sitter. Coverage goes from 0% → ~80% on first analyze. No LLM.
Agent summaries:store_understanding stores a summary permanently with a summary_hash (snapshot of content_hash at write time).
If source changes → summary_stale: true in get_context → agent re-reads and updates
If source unchanged → store_understanding returns skipped: true → no duplicate writes
Pass force: true to overwrite regardless
Pass tags: ["label", ...] to attach agent-owned tags — these survive re-index
Priority: Agent summaries are never overwritten by auto-summaries. Re-analyzing preserves agent work.
Index-time enrichment (v0.6.1)
Every loom analyze run now enriches the graph with additional metadata beyond raw symbols:
File fingerprinting — SHA-256 + mtime stored in file_fingerprints table; only changed files are re-parsed (incremental by default)
Complexity classification — each function/method tagged SIMPLE, MODERATE, or COMPLEX based on cyclomatic complexity
Tag search — tag:X syntax in search_code and loom query; multiple tags use AND semantics (e.g. "tag:auth login")
Enhanced context packets — get_context now returns complexity, tags, and tested_by fields for function/method nodes
Agent tags — store_understanding accepts tags: list[str]; stored with source="agent" and survive re-index
Plugin system
loom install supports these platforms out of the box: claude-code, cursor, windsurf, codex.
loom install --list-plugins # see supported platforms
loom install --platform cursor # install only for Cursor
Need another platform? The list is a small static table in src/loom/cli/install.py — PRs welcome.
Session delta — how it works
Session 1: Session 2:
start_session() get_delta(previous_session_id)
[work on auth.py] → {changed: [2 fns], deleted: [], unchanged: 310}
session_id stored Only read the 2 changed functions. Skip the rest.
Delta uses updated_at on nodes — only bumped when content_hash changes. Safe against false positives from re-analyzing identical files.
Token savings tracking
Every search_code hit with a cached summary records how many tokens were saved (source line count × 15 — no extra deps, no index overhead).
loom savings # CLI dashboard
Total tokens saved: 127,400
Cache hits: 847 (agent: 23 auto: 824)
agent = store_understanding summaries (provably skipped file reads)
auto = metadata summaries from loom analyze
Inside Claude Code, call get_savings() MCP tool or load loom://savings resource for the same report.
search_code results include tokens_saved and summary_type per hit when a summary is cached.
Auto-indexing
When installed via the Claude Code plugin, Loom auto-indexes the current project on first session start — no manual loom analyze needed. If the DB is empty when the MCP server starts, indexing runs in the background while the session continues.
