Skip to content
Back to search

loom

MarketplaceWorks with Claude CodeGitHub

ClickHouse Loom: shared long-term memory and code intelligence for AI coding agents, self-hosted.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 17 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ClickHouse/loom with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ClickHouse/loom'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/clickhouse--loom/badge.svg)](/listings/clickhouse--loom)

HTML

<a href="/listings/clickhouse--loom"><img src="/api/listings/clickhouse--loom/badge.svg" alt="findsafeskills safety rating" /></a>

Install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 41 lines
  1. {
  2. "name": "loom",
  3. "owner": {
  4. "name": "ClickHouse"
  5. },
  6. "description": "ClickHouse Loom: shared long-term memory and code intelligence for AI coding agents, self-hosted.",
  7. "plugins": [
  8. {
  9. "name": "loom",
  10. "source": "./integrations/claude-code-plugin",
  11. "description": "Shared long-term memory and code intelligence for Claude Code: MCP tools to save and recall decisions across sessions, hooks that capture each session with no model call, and a code index that answers structure questions without whole-file reads.",
  12. "license": "Apache-2.0",
  13. "category": "memory",
  14. "tags": ["agent-memory", "long-term-memory", "code-intelligence", "code-search", "mcp", "clickhouse"],
  15. "relevance": {
  16. "topic": "Loom",
  17. "signals": {
  18. "cli": ["loom"],
  19. "filesRead": ["**/loom.yaml", "**/loom.example.yaml", "**/.loom/config.json"],
  20. "manifestDeps": [
  21. {
  22. "file": "[/\\\\](pyproject\\.toml|requirements[^/\\\\]*\\.txt)$",
  23. "pattern": "clickhouse[-_.]loom"
  24. },
  25. {
  26. "file": "[/\\\\]package\\.json$",
  27. "pattern": "\"@clickhouse/loom\"\\s*:"
  28. }
  29. ]
  30. }
  31. }
  32. },
  33. {
  34. "name": "loom-code-skill",
  35. "source": "./",
  36. "description": "Code search and code intelligence for repositories in a Loom code index (the loom-code Agent Skill: code.* first, then read only that), and the loom Agent Skill: how an agent uses Loom. No hooks; GitHub Copilot CLI also adds the loom MCP server.",
  37. "license": "Apache-2.0",
  38. "category": "code-intelligence"
  39. }
  40. ]
  41. }
README.md · README · 303 lines
  1. <h1 align="center">ClickHouse Loom</h1>
  2. <p align="center">
  3. <b>Shared memory, document search and code intelligence for AI agents.</b><br>
  4. For Claude Code, Codex, Cursor and your own agents.
  5. </p>
  6. <p align="center">
  7. <a href="https://pypi.org/project/clickhouse-loom/"><img alt="Python SDK on PyPI" src="https://img.shields.io/pypi/v/clickhouse-loom?label=python%20sdk"></a>
  8. <a href="https://www.npmjs.com/package/@clickhouse/loom"><img alt="TypeScript SDK on npm" src="https://img.shields.io/npm/v/%40clickhouse%2Floom?label=typescript%20sdk"></a>
  9. <a href="./LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
  10. <a href="https://glama.ai/mcp/servers/ClickHouse/loom"><img alt="MCP server score" src="https://glama.ai/mcp/servers/ClickHouse/loom/badges/score.svg"></a>
  11. <a href="https://github.com/ClickHouse/loom/actions/workflows/ci.yml?query=branch%3Amain+event%3Apush"><img alt="CI on main" src="https://github.com/ClickHouse/loom/actions/workflows/ci.yml/badge.svg?branch=main&amp;event=push"></a>
  12. <a href="https://scorecard.dev/viewer/?uri=github.com/ClickHouse/loom"><img alt="OpenSSF Scorecard" src="https://api.scorecard.dev/projects/github.com/ClickHouse/loom/badge"></a>
  13. </p>
  14. <p align="center">
  15. <!-- languages -->
  16. English · <a href="./i18n/zh-CN/README.md">简体中文</a> · <a href="./i18n/ja/README.md">日本語</a> · <a href="./i18n/ko/README.md">한국어</a> · <a href="./i18n/pt-BR/README.md">Português (Brasil)</a> · <a href="./i18n/es/README.md">Español</a>
  17. <!-- /languages -->
  18. </p>
  19. <p align="center">
  20. <a href="#what-loom-is-for">What Loom is for</a> ·
  21. <a href="#measured-results">Benchmarks</a> ·
  22. <a href="#get-started">Get started</a> ·
  23. <a href="#why-loom">Capabilities</a> ·
  24. <a href="#integrations">Integrations</a> ·
  25. <a href="https://clickhouse.github.io/loom/">Documentation</a>
  26. </p>
  27. <p>
  28. <img src="./docs/assets/screenshots/memories.webp" width="32%" alt="Loom dashboard showing shared agent memories, a pinned fact and flagged conflicts">
  29. <img src="./docs/assets/screenshots/document-search.webp" width="32%" alt="Library search: three passages from a refunds policy, an on-call runbook and an FX note, each cited by document, revision and lines">
  30. <img src="./docs/assets/screenshots/code-callers.webp" width="32%" alt="A repository's Explore tab: payments.fx.convert with its definition and callers">
  31. </p>
  32. Loom is an open-source, self-hosted MCP server that gives your agents long-term, shared
  33. memory: what one agent learns in a session, the next agent or tool can find.
  34. Agents connect through MCP, HTTP, Python or TypeScript. Self-host with Docker or
  35. [on Kubernetes with the Helm chart](./docs/operations/kubernetes.md); agent context and
  36. index data live in [ClickHouse](./docs/use-cases/self-hosted-clickhouse.md), and a
  37. deployment can choose [Postgres at first boot](./docs/operations/postgres.md) for live
  38. memory and knowledge state. The dashboard brings memories, repositories, tasks and runs
  39. into one place.
  40. ## What Loom is for
  41. - **Long-term memory shared across your coding agents**, with plugins that load context
  42. at session start and capture the session as it runs.
  43. [Agent memory](./docs/use-cases/agent-memory.md) ·
  44. [Connect a coding agent](./docs/getting-started/connect-a-coding-agent.md)
  45. - **Memory for an agent application**, per user, from the Python or TypeScript
  46. SDK. [Your first agent](./docs/getting-started/first-agent.md)
  47. - **A multi-user MCP memory server** with namespaces, roles and tokens.
  48. [Multi-user mode](./docs/getting-started/quickstart.md#start-in-multi-user-mode) ·
  49. [Namespaces and sharing](./docs/features/namespaces-and-sharing.md)
  50. - **A code index of your repositories** that coding agents query for definitions,
  51. callers and change impact. [Code index](./docs/use-cases/code-intelligence.md) ·
  52. [Language support and limits](./docs/features/code-index/overview.md#language-support)
  53. - **Memories linked to the code they are about**, which follow it through refactors, are
  54. flagged when it changes and appear when an agent reads or edits it.
  55. [Memory linked to code](./docs/use-cases/memory-linked-to-code.md)
  56. - **Lower model cost for coding agents**, as [measured](#measured-results) below.
  57. [Coding-agent cost](./docs/use-cases/coding-agent-cost.md)
  58. - **Document search with citations (RAG)**, including PDF, `.docx` and `.pptx` files the
  59. extractor service converts. [Document search](./docs/use-cases/document-search.md)
  60. - **Shared context for multi-agent workflows**: shared memory, task inboxes and
  61. decisions. [Multi-agent](./docs/use-cases/multi-agent.md)
  62. - **Memory, recall, audit and erasure for autonomous agents.**
  63. [Autonomous agents](./docs/use-cases/autonomous-agents.md)
  64. - **A record of agent work**, with searchable conversations (when recording is on),
  65. session briefs to resume from, runs with their goals, outcomes and model costs when
  66. supplied, and PR and tracker history.
  67. [Runs and PR history](./docs/use-cases/runs-and-pr-history.md)
  68. Every use case, and when another tool fits better: [use cases](./docs/use-cases/index.md).
  69. Loom is not an in-process library for one agent's short-lived memory, nor an agent
  70. framework. [When Loom does not fit](./docs/getting-started/overview.md#when-it-does-not-fit)
  71. ## Measured results
  72. | Evaluation | With Loom | Without Loom | Efficiency gain | Scope |
  73. | ------------------------------ | --------- | ------------ | ---------------------------------- | ---------------------------------- |
  74. | Coding-agent answer quality | **0.84** | 0.78 | **20% lower** model cost | 24 questions × 3 paired runs |
  75. | Coding-agent file localization | **96.4%** | 91.4% | **21% lower** model cost | 36 questions × 10 paired runs |
  76. | Memory vs full-history answers | **94%** | 90% | **91% fewer** reader prompt tokens | 100 paired LongMemEval-S questions |
  77. Both coding setups use Claude Code (`claude-sonnet-5`) on the ClickHouse codebase;
  78. cost is the whole session's model bill, excluding Loom's server-side model calls, hosting
  79. and indexing. Answer quality
  80. measures coverage of a verified answer's key points, with a contradiction penalty.
  81. File localization counts whether the right file is among the up to three files the agent is
  82. asked to name at the end of its answer.
  83. The memory row compares retrieved memories with full conversation history using
  84. the same `gpt-5` reader. Token savings exclude memory construction; the 94% vs 90%
  85. accuracy difference is descriptive, not statistically established.
  86. **Separately, Loom's `memory.ask` configuration scored 96.6% answer accuracy on all
  87. 500 LongMemEval-S questions.** This is a product evaluation with its own configured
  88. answer models, not the fixed-reader comparison above.
  89. Results are specific to the tested workloads.
  90. [Protocols and reproducible artifacts](./docs/benchmarks/results.md) ·
  91. [detailed results](#benchmark-details) ·
  92. [evaluate on your workload](./docs/getting-started/evaluate.md)
  93. ## Get started
  94. ### 1. Choose your Docker setup
  95. - **Personal use—the default:** no login, localhost-only access and a `dev/local`
  96. namespace. One person can connect multiple agents.
  97. - **Team use:** authenticated accounts and namespace access controls.
  98. [Start in multi-user mode from the first boot](./docs/getting-started/quickstart.md#start-in-multi-user-mode).
  99. Both modes support the same Loom features, including configured LLMs and embeddings.
  100. Single-user is not a reduced-feature edition. You can also
  101. [switch an existing installation without deleting its data](./docs/getting-started/quickstart.md#2-open-the-dashboard);
  102. grant new accounts access to the existing namespaces.
  103. To try it with nothing installed, open it in a codespace:
  104. [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/ClickHouse/loom?quickstart=1)
  105. ([what it runs and who can reach it](./docs/getting-started/quickstart.md#try-it-in-github-codespaces))
  106. For the default personal installation, with Docker installed (on Windows, in a WSL 2
  107. terminal where `docker` works: Docker Desktop with its WSL integration on, or Docker Engine
  108. installed in the distribution):
  109. ```bash
  110. curl -fsSL https://github.com/ClickHouse/loom/releases/latest/download/install.sh -o loom-install.sh && sh loom-install.sh && rm loom-install.sh
  111. ```
  112. Run it from your home directory, or another
  113. [directory only you can write to](./docs/getting-started/quickstart.md#fast-path-released-image-no-clone).
  114. The installer starts Loom and ClickHouse, applies migrations and prints the dashboard URL:
  115. **http://localhost:7777/**; on a new install it then checks that a memory saves and reads
  116. back. On a terminal it also offers to connect the coding agents it finds (Claude Code, Codex,
  117. VS Code) and, on a new install, opens the dashboard. The image includes the server,
  118. workers, dashboard and Python, TypeScript and Go compiler indexers, plus the C++ one on
  119. `amd64`; TypeScript dependencies are prepared automatically. [Quickstart and pinned releases](./docs/getting-started/quickstart.md)
  120. The installation lives in `~/.loom` (`LOOM_INSTALL_DIR` chooses another directory): the
  121. Compose file and the startup settings in `~/.loom/.env`. Running the install command again
  122. upgrades in place and keeps your `.env` settings.
  123. Keep single-user mode localhost-only. For shared access, follow the
  124. [team deployment guide](./docs/operations/deployment.md#identity-modes), including TLS.
  125. ### 2. Configure models and API keys
  126. **The stock installation boots without keys or network.** Storage, the dashboard,
  127. structural code indexing and semantic search work, on a small local embedding model the
  128. image carries; the fake LLM gives no AI-generated answers.
  129. | Component | Configure for real use | Without configuration |
  130. | ---------- | -------------------------------------------------- | --------------------------------------------------------------------------- |
  131. | Embeddings | Provider, embedding model, dimensions and API key. | `local` (bge-small on CPU): semantic retrieval, weaker than a hosted model. |
  132. | LLM | Provider, model and API key. | `fake-echo-1`: no meaningful extraction, summaries or answers. |
  133. Open **Settings → Models & keys**, choose both providers and models, enter their
  134. keys, then click **Test & apply**. No Docker restart is needed; changing the embedding
  135. space rebuilds the existing index. The dashboard's embedding choices are hosted
  136. providers: to keep `local` and add an LLM, set the LLM lines in `~/.loom/.env` instead
  137. ([Models and keys](docs/getting-started/models-and-keys.md#claude-for-the-llm)).
  138. **One OpenAI API key can serve both roles.** Claude needs a separate embedding provider.
  139. OpenAI, Gemini and OpenAI-compatible embedding endpoints are supported. Your agent's
  140. CLI login or subscription does not supply Loom's provider keys.
  141. Prefer environment configuration? Edit `~/.loom/.env`, then recreate the server:
  142. ```bash
  143. docker compose --project-directory "$HOME/.loom" up -d --force-recreate loom
  144. ```
  145. A key alone does not change the pinned models (the local embedder and the fake LLM); set
  146. the provider and model too.
  147. Saved dashboard settings take precedence over `.env`. Follow
  148. [models and API keys](./docs/getting-started/models-and-keys.md) for provider recipes
  149. and health checks.
  150. **Everything else is in one file.** [`loom.example.yaml`](./loom.example.yaml) lists
  151. every setting with its default and what it does, by area: the ClickHouse connection,
  152. timeouts and budgets, rate limits, workers, and the `*_enabled` switches that turn
  153. features on and off. Set any of them as `LOOM_<NAME>` in `~/.loom/.env` and recreate the
  154. server; a deployment that mounts a config file can set them in a copy of this file
  155. instead ([how settings are read](./docs/operations/deployment.md#how-settings-are-read)). One marked
  156. `live` also changes while Loom runs: `loom settings set <name> <value>`, or Admin → Deployment
  157. settings. `loom settings list --changed` shows what differs from the defaults and
  158. where each value came from ([runtime settings](./docs/operations/runtime-settings.md)).
  159. ### 3. Connect your agents
  160. If the installer connected your agent, skip the commands below. On the machine running a
  161. personal installation, the plugins need no token:
  162. ```bash
  163. # Claude Code
  164. claude plugin marketplace add ClickHouse/loom
  165. claude plugin install loom@loom
  166. # Codex
  167. codex plugin marketplace add ClickHouse/loom
  168. codex plugin add loom@loom
  169. ```
  170. Start a new session; the first one connects to `http://localhost:7777`. In Codex, run
  171. `codex` interactively once and approve the plugin's hooks; until then only the tools
  172. work. Tell the agent something worth keeping, then ask about it in the next session.
  173. For Cursor, on a Teams or Enterprise plan, a team admin can import this repository as a
  174. team marketplace; its [Cursor plugin](./docs/features/integrations/cursor.md#plugin),
  175. untested in Cursor, installs the MCP entry and Loom's skills. On the machine running a
  176. personal installation, the button below adds the [local MCP
  177. entry](./docs/features/integrations/cursor.md#mcp-tools), which needs no token:
  178. [![Add Loom to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=loom&config=eyJ1cmwiOiJodHRwOi8vbG9jYWxob3N0Ojc3NzcvbWNwP3Rvb2xzZXQ9Y29kaW5nIn0%3D)
  179. For VS Code agent mode on the machine running a personal installation, the buttons below
  180. add the [local MCP entry](./docs/features/integrations/vscode.md#local-single-user-server),
  181. which needs no token:
  182. [![Add Loom to VS Code](https://img.shields.io/badge/VS_Code-Add_Loom-0098FF?logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522loom%2522%252C%2522type%2522%253A%2522http%2522%252C%2522url%2522%253A%2522http%253A%252F%252Flocalhost%253A7777%252Fmcp%2522%257D)
  183. [![Add Loom to VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Add_Loom-24bfa5?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522loom%2522%252C%2522type%2522%253A%2522http%2522%252C%2522url%2522%253A%2522http%253A%252F%252Flocalhost%253A7777%252Fmcp%2522%257D)
  184. For a team server, pass `--config server_url=… --config token=…` to Claude Code, or
  185. point Codex at it as described in
  186. [connect a coding agent](./docs/getting-started/connect-a-coding-agent.md). Create
  187. tokens in **Settings → Tokens**. Cursor and other MCP clients, and
  188. [the SDK](./docs/getting-started/first-agent.md), are covered there too.
  189. ## Why Loom
  190. - **Memory that carries forward.** Share decisions and findings across agents and
  191. sessions. Each fact records who wrote it, version history and conflict review make
  192. corrections traceable, and a namespace can be rolled back to any point in time.
  193. [Memory](./docs/concepts/memory.md)
  194. - **Code intelligence with evidence.** Find definitions, callers, change impact and
  195. relevant tests; connect code to commits, pull requests and issues. Use source
  196. locations, completeness signals and per-tier freshness to check a result.
  197. [Code index](./docs/features/code-index/overview.md)
  198. - **Grounded retrieval.** Search permitted memories, documents, conversations and
  199. tracker records. Answers cite their sources; low-confidence retrieval can abstain.
  200. [Retrieval](./docs/concepts/retrieval-and-ranking.md)
  201. - **Multi-agent handoffs.** Assign work through durable task inboxes with leases,
  202. retries, review rules and outcomes. Your agents execute the workflow; Loom
  203. preserves the handoffs. [Task queues](./docs/features/tasks-and-decisions.md)
  204. - **Control over agent data.** Manage namespace access, provenance, retention, audit
  205. records and verified erasure. Context remains queryable in ClickHouse.
  206. [Security](./docs/architecture/security.md)
  207. ## Integrations
  208. | Integration | What it connects |
  209. | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
  210. | [Claude Code](./docs/features/integrations/claude-code.md), [Codex](./docs/features/integrations/codex.md), [Cursor](./docs/features/integrations/cursor.md) and [other MCP clients](./docs/features/integrations/mcp-clients.md) ([all integrations](./docs/features/integrations/index.md)) | Memory and code intelligence in your existing agent workflow. |
  211. | [Python](./docs/reference/python-sdk.md), [TypeScript](./docs/reference/typescript-sdk.md) and [HTTP](./docs/reference/operations.md) | Your own agents and applications. |
  212. | [Langfuse](./docs/features/integrations/langfuse.md) | Request traces, model costs, retrieval scores and prompt-version attribution. |
  213. | [ClickStack / HyperDX](./docs/features/integrations/clickstack.md) | OpenTelemetry traces, logs and metrics in ClickHouse. |
  214. Langfuse and ClickStack are optional integrations, not bundled services in the Docker stack.
  215. ## Benchmark details
  216. ### Detailed retrieval, reader and code-search results
  217. | Evaluation | Result |
  218. | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
  219. | LongMemEval-S evidence retrieval (500 questions) | **98.6%** of questions with at least one supporting session in the first 30 memories. |
  220. | LongMemEval-S fixed `gpt-5` reader (500 questions) | **92.0%** answer accuracy from the top 200 memories. |
  221. | LoCoMo (all 10 conversations) | **89.6%** answer accuracy; **90.8%** correct abstentions on adversarial questions. |
  222. | MemoryAgentBench fact-question sample (500 questions) | **99.0%** SubEM; **95.7%** token-overlap F1 on generated answers. |
  223. | Conceptual code search (36 questions) | Gold-file recall **91.2%** at 5 / **97.2%** at 10; MRR **0.91**. |
  224. | SWE-bench Verified file localization (200 issues) | Issues with a changed file in the first 10: **82%** vs **57%** for BM25; **76.5%** in the first 5. |
  225. | Tracker duplicate detection (104 pairs) | Recorded older duplicate ranked first **87.5%** of the time. |
  226. These measure different tasks, not one aggregate score. SWE-bench measures
  227. file localization, not issue resolution. The [results ledger](./docs/benchmarks/results.md)
  228. includes scoring definitions, small-sample evaluations, weaker and negative findings,
  229. and the full protocols, models and artifacts.
  230. [Methodology](./docs/benchmarks/methodology.md) ·
  231. [coverage and known gaps](./docs/benchmarks/coverage.md) ·
  232. [run the benchmarks](./docs/benchmarks/running.md)
  233. ## Documentation and contributing
  234. For shared agent context, code intelligence and permissioned retrieval, start with the
  235. [documentation](https://clickhouse.github.io/loom/). For deployment requirements, see the
  236. [prerequisites](./docs/getting-started/overview.md#prerequisites).
  237. [Deployment](./docs/operations/deployment.md) · [FAQ](./docs/faq.md) ·
  238. [Contributing](./CONTRIBUTING.md) · [Security reporting](./SECURITY.md) ·
  239. [`llms.txt`](https://clickhouse.github.io/loom/llms.txt) ·
  240. [`llms-full.txt`](https://clickhouse.github.io/loom/llms-full.txt)
  241. Apache-2.0 · [License](./LICENSE) · [Notice](./NOTICE)
bench/memorydata/loom_adapter.py · Bundled script · 258 lines · 1 finding marked
  1. """Loom as a MemoryData method (harness: github.com/OpenDataBox/MemoryData).
  2. This file is the copy kept in the loom repo; drop it at methods/loom/loom_adapter.py
  3. in a MemoryData checkout and follow bench/memorydata/README.md for the six
  4. name-list edits the harness needs.
  5. Contract mirrored from the harness's raw-text reference adapter
  6. (methods/<system>/*_adapter.py): the harness calls
    • Note: Usual in code (tag names in paths and patterns): Contains a <system> block, a common wrapper for instructions hidden in a tool description
    • Line 8 on GitHub
  7. `add_chunk(content, timestamp)` once per context chunk while memorizing and
  8. `retrieve(question) -> list[str]` per query; it generates the answer itself
  9. from the returned texts and scores LoCoMo source recall by parsing
  10. `[LOCOMO_META chunk_id=… source_ids=…]` headers out of them.
  11. Two arms, chosen by `loom_mode`:
  12. * `verbatim` — each chunk is stored whole with `memory.set` (the storage text,
  13. META header included) under `session_id = chunk_id`. Retrieval returns the
  14. stored value via `bodies=unit`, so the META header survives and recall is
  15. scored the way the harness scores its raw-text reference arm.
  16. * `extract` — each chunk goes through `memory.set_from_messages` (loom's
  17. schema-free LLM extraction) with `session_id = chunk_id`; extracted facts
  18. do not carry the META header, so retrieve() re-attaches it from the hit's
  19. `session_id` through a chunk_id → source_ids map kept by
  20. the adapter. This is what makes loom's fact plane scoreable on their
  21. Recall@k axis.
  22. One loom namespace per (dataset, context): `<prefix>-<sub_dataset>-<context>`,
  23. created lazily by the first write. Env: LOOM_BASE_URL (default
  24. http://127.0.0.1:7777), LOOM_API_KEY (required).
  25. """
  26. from __future__ import annotations
  27. import json
  28. import os
  29. import re
  30. import sys
  31. import time
  32. from typing import Any
  33. import httpx
  34. from utils.locomo_utils import (
  35. build_locomo_storage_text,
  36. parse_locomo_metadata,
  37. parse_locomo_source_ids,
  38. strip_locomo_metadata,
  39. )
  40. _SESSION_HEADER_RE = re.compile(r"^Session (\d+)(?: \((.*?)\))?\s*$")
  41. _TURN_RE = re.compile(r"^([^:\n]{1,80}):\s(.*)$")
  42. class LoomAdapter:
  43. def __init__(
  44. self,
  45. *,
  46. base_url: str,
  47. token: str,
  48. namespace: str,
  49. retrieve_num: int,
  50. mode: str = "verbatim",
  51. search_mode: str = "semantic",
  52. bodies: str = "unit",
  53. body_budget_tokens: int = 6000,
  54. request_timeout_s: float = 120.0,
  55. state_path: str | None = None,
  56. org: str | None = None,
  57. ) -> None:
  58. self.org = org or os.environ.get("LOOM_ORG") or "dev"
  59. self.base_url = base_url.rstrip("/")
  60. self.token = token
  61. self.namespace = namespace
  62. self.retrieve_num = int(retrieve_num)
  63. self.mode = mode
  64. self.search_mode = search_mode
  65. self.bodies = bodies
  66. self.body_budget_tokens = int(body_budget_tokens)
  67. self.state_path = state_path
  68. self._client = httpx.Client(timeout=request_timeout_s, trust_env=False)
  69. self._n = 0
  70. # chunk_id -> source_ids, so extracted facts can be scored for recall
  71. self._sources: dict[str, list[str]] = {}
  72. self.write_seconds = 0.0
  73. self.write_tokens_in = 0
  74. self.write_tokens_out = 0
  75. self.write_calls = 0
  76. self.write_errors = 0
  77. if state_path and os.path.exists(state_path):
  78. try:
  79. saved = json.loads(open(state_path, encoding="utf-8").read())
  80. self._n = int(saved.get("n", 0))
  81. self._sources = dict(saved.get("sources", {}))
  82. except Exception: # noqa: BLE001
  83. pass
  84. # ------------------------------------------------------------------ http
  85. def _identity(self) -> dict[str, str]:
  86. return {"org": self.org, "namespace": self.namespace, "agent": "memorydata", "user_id": "-"}
  87. def _post(self, op: str, body: dict[str, Any], attempts: int = 4) -> dict[str, Any]:
  88. url = f"{self.base_url}/v1/{op}"
  89. last: Exception | None = None
  90. for attempt in range(attempts):
  91. try:
  92. r = self._client.post(
  93. url, json=body, headers={"Authorization": f"Bearer {self.token}"}
  94. )
  95. if r.status_code == 429 or r.status_code >= 500:
  96. delay = float(r.headers.get("Retry-After") or (1.5 * (attempt + 1)))
  97. time.sleep(min(delay, 20.0))
  98. last = RuntimeError(f"{op}: HTTP {r.status_code}")
  99. continue
  100. if r.status_code >= 400:
  101. # 4xx is a contract error, not a transient: surface the body once.
  102. raise RuntimeError(f"{op}: HTTP {r.status_code} {r.text[:400]}")
  103. return r.json()
  104. except httpx.HTTPError as e:
  105. last = e
  106. time.sleep(1.5 * (attempt + 1))
  107. raise RuntimeError(f"{op} failed after {attempts} attempts: {last}")
  108. # --------------------------------------------------------------- parsing
  109. @staticmethod
  110. def _parse_turns(text: str, fallback_timestamp: str | None) -> tuple[list[dict[str, str]], str]:
  111. """Split a LoCoMo chunk ("Session N (date)" header, "Speaker: text"
  112. lines) into loom messages. Returns (messages, observation_date)."""
  113. messages: list[dict[str, str]] = []
  114. date = ""
  115. for raw in text.split("\n"):
  116. line = raw.strip()
  117. if not line:
  118. continue
  119. m = _SESSION_HEADER_RE.match(line)
  120. if m:
  121. date = (m.group(2) or "").strip() or date
  122. continue
  123. t = _TURN_RE.match(line)
  124. if t:
  125. speaker, body = t.group(1).strip(), t.group(2).strip()
  126. messages.append({"role": "user", "content": f"{speaker}: {body}", "name": speaker})
  127. elif messages:
  128. messages[-1]["content"] += "\n" + line
  129. else:
  130. messages.append({"role": "user", "content": line})
  131. return messages, (date or (fallback_timestamp or ""))
  132. # ---------------------------------------------------------------- write
  133. def add_chunk(self, content: str, timestamp: str | None = None) -> None:
  134. raw = str(content or "")
  135. metas = parse_locomo_metadata(raw)
  136. chunk_id = str(metas[0].get("chunk_id") if metas else "") or f"chunk_{self._n + 1:05d}"
  137. source_ids = (
  138. list(metas[0].get("source_ids") or []) if metas else parse_locomo_source_ids(raw)
  139. )
  140. self._sources[chunk_id] = source_ids
  141. self._n += 1
  142. t0 = time.perf_counter()
  143. try:
  144. if self.mode == "extract":
  145. messages, obs_date = self._parse_turns(strip_locomo_metadata(raw), timestamp)
  146. body: dict[str, Any] = {
  147. **self._identity(),
  148. "session_id": chunk_id,
  149. "messages": messages
  150. or [{"role": "user", "content": strip_locomo_metadata(raw)}],
  151. }
  152. if obs_date:
  153. body["observation_date"] = obs_date
  154. resp = self._post("memory.set_from_messages", body)
  155. self.write_tokens_in += int(resp.get("tokens_in") or 0)
  156. self.write_tokens_out += int(resp.get("tokens_out") or 0)
  157. else:
  158. # Whole chunk, META header kept, one row keyed by the chunk id.
  159. # No per-chunk session_id here: point reads (memory.get and the
  160. # bodies=unit expansion) resolve a key under the READ identity's
  161. # session, so a row written under session=chunk_id would come
  162. # back as the 1,200-char clip. The META header in the value
  163. # already names the sources; the extract arm is the one that
  164. # needs session_id for provenance.
  165. self._post(
  166. "memory.set",
  167. {
  168. **self._identity(),
  169. "memory_key": chunk_id,
  170. "memory_type": "semantic",
  171. "value": raw,
  172. "tags": ["memorydata", "locomo"],
  173. },
  174. )
  175. self.write_calls += 1
  176. except Exception:
  177. self.write_errors += 1
  178. raise
  179. finally:
  180. self.write_seconds += time.perf_counter() - t0
  181. self._save_state()
  182. # ----------------------------------------------------------------- read
  183. def retrieve(self, question: str) -> list[str]:
  184. resp = self._post(
  185. "memory.search",
  186. {
  187. **self._identity(),
  188. "query": question,
  189. "top_k": self.retrieve_num,
  190. "search_mode": self.search_mode,
  191. "namespace_scope": "this",
  192. "auto_touch": False,
  193. "bodies": self.bodies,
  194. "body_budget_tokens": self.body_budget_tokens,
  195. },
  196. )
  197. out: list[str] = []
  198. for h in resp.get("results") or []:
  199. text = h.get("value") if isinstance(h.get("value"), str) else h.get("content_excerpt")
  200. text = str(text or "").strip()
  201. if text.startswith('"'):
  202. # loom stores a string value JSON-encoded; the excerpt / unit
  203. # body comes back in that form. Decode so the META header and
  204. # the newlines are the ones the harness wrote.
  205. try:
  206. text = str(json.loads(text))
  207. except ValueError:
  208. text = text.strip('"').replace("\\n", "\n")
  209. if not text:
  210. continue
  211. if not parse_locomo_source_ids(text):
  212. # Extracted fact: recover the source ids from the session it
  213. # was written under so recall can be scored.
  214. sid = str(h.get("session_id") or "")
  215. srcs = self._sources.get(sid)
  216. if srcs:
  217. text = build_locomo_storage_text(text, sid, srcs)
  218. prefix = str(h.get("valid_at") or "").strip()
  219. out.append(
  220. f"{prefix} {text}".strip()
  221. if prefix and not text.startswith("[LOCOMO_META")
  222. else text
  223. )
  224. return out
  225. def ask(self, question: str) -> str: # the harness answers from retrieve(); kept for parity
  226. return "\n".join(self.retrieve(question))
  227. def finalize(self) -> None:
  228. self._save_state()
  229. def _save_state(self) -> None:
  230. if not self.state_path:
  231. return
  232. try:
  233. # A bare filename has no directory part, and makedirs("") raises.
  234. if os.path.dirname(self.state_path):
  235. os.makedirs(os.path.dirname(self.state_path), exist_ok=True)
  236. with open(self.state_path, "w", encoding="utf-8") as f:
  237. json.dump({"n": self._n, "sources": self._sources, "namespace": self.namespace}, f)
  238. except Exception as e: # noqa: BLE001 — the run continues; a resume will re-ingest
  239. print(f"[loom adapter] state not saved to {self.state_path}: {e}", file=sys.stderr)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.