Website · Quickstart · Install · Architecture · Docs
Loomem is the open-source context layer for your LLM agents — a single Rust binary on your laptop, served over MCP, that feeds Claude, ChatGPT, Codex, or any MCP client the facts, decisions, and history they need to do real work for you. Swap the model, switch the tool; your context follows.
Loomem stores structured knowledge extracted from conversations, and serves it back to any MCP-capable client (Claude, ChatGPT, Codex, Cursor, your own agents) through hybrid retrieval:
- Hybrid search — BM25 (Tantivy) + vector embeddings + entity graph signals, fused with a weighted hybrid score (vector 0.6 / BM25 0.4).
- Consolidation — background workers merge related facts, resolve contradictions, and let stale ones decay ("dreaming").
- Bitemporal model — facts carry both ingestion time and event time (
valid_from/valid_until), so "what did I know in March" and "what happened in March" are different queries. - Entity graph — people, projects, and technologies are extracted into a graph with aliases and relations, used both for retrieval and exploration.
- MCP-native — 15
memory_*tools over the standard MCP HTTP transport, including OAuth dynamic client registration for remote connectors. - Encryption at rest (optional) — field-level AES-GCM envelope encryption with a master key from the environment.
Built in Rust on RocksDB + Tantivy. Single binary, no external services required.
Status: early. The engine has been in daily personal use for a while, but the public API and storage format may still change. Expect rough edges; issues and PRs are welcome.
Quickstart
From nothing to Claude remembering things across conversations, on macOS or Linux. Each step is independent — run them in order.
1. Install the binaries (no sudo; lands in ~/.loomem):
curl -fsSL https://raw.githubusercontent.com/vvooki-sys/loomem/main/install.sh | sh
2. Put ~/.loomem/bin on your PATH (the installer prints this too):
echo 'export PATH="$HOME/.loomem/bin:$PATH"' >> ~/.zshrc # or ~/.bashrc
exec $SHELL
3. Download the local embedding model (~113 MB, once). The installer does not fetch it, and the server refuses to start without it:
curl -fsSL https://raw.githubusercontent.com/vvooki-sys/loomem/main/scripts/fetch-embedding-model.sh | sh
4. Set an LLM key for extraction, consolidation and dreaming, or accept keyless mode (see the FAQ):
export OPENAI_API_KEY="sk-..." # or: export LOOMEM_ALLOW_KEYLESS=1
5. Start the server (config is already seeded in ~/.loomem):
cd ~/.loomem && loomem-server
6. Check it's alive (in another terminal):
curl http://localhost:3030/health
# {"status":"ok","version":"0.5.4"}
The installer uses port 3030 by default and asks for an alternative if it's already taken (set
LOOMEM_PORTto skip the prompt). If you picked a different port, use it in the commands below.
7. Connect Claude Code:
claude mcp add --transport http loomem http://localhost:3030/mcp
7b. Using the Claude desktop app (or Cowork) instead? It connects to local servers over stdio, not HTTP, so bridge it in claude_desktop_config.json, then restart Claude. Native, no Node (Loomem ≥ v0.2.1):
{ "mcpServers": { "loomem": { "command": "/absolute/path/to/.loomem/bin/loomem-cli", "args": ["mcp-stdio", "--url", "http://127.0.0.1:3030"] } } }
(Any version, needs Node: "command": "npx", "args": ["-y", "mcp-remote", "http://127.0.0.1:3030/mcp", "--allow-http"].) See Connect an MCP client for auth and details.
8. Try it. In Claude: "Remember that I prefer dark mode in all my tools." Then, in a fresh conversation: "What do you know about my preferences?" — the answer comes back from Loomem.
Other clients (claude.ai, ChatGPT, OpenClaw), TLS/remote exposure, and the full options matrix are below and in docs/installation.md.
Install
One-liner (prebuilt binaries, macOS + Linux)
curl -fsSL https://raw.githubusercontent.com/vvooki-sys/loomem/main/install.sh | sh
Installs loomem-server, loomem-cli, and loomem-migrate to ~/.loomem/bin (no sudo) and drops config templates into ~/.loomem. Pin a version with LOOMEM_VERSION=v0.2.0, change the location with LOOMEM_INSTALL_DIR. Archives are verified against SHA256SUMS from the releases page. The installer does not download the local embedding model: fetch it as in step 3 of the Quickstart.
Full guide — requirements, version pinning, manual checksum verification, upgrading, uninstalling, troubleshooting: docs/installation.md.
From source
git clone https://github.com/vvooki-sys/loomem.git
cd loomem
cp entities.toml.example entities.toml # personal entity config (gitignored)
(cd loomem-dashboard && npm ci && npm run build) # dashboard, embedded at compile time
./scripts/fetch-embedding-model.sh # local embedding model → ~/.loomem/models
cargo build --release -p loomem-server -p loomem-cli
export OPENAI_API_KEY="sk-..." # or LOOMEM_ALLOW_KEYLESS=1 to run without a key (see below)
cargo run --release -p loomem-server
# server listens on http://127.0.0.1:3030, data in ./data
Requires Rust (stable), Node.js (for the dashboard) and libclang (for the RocksDB build): apt install libclang-dev on Debian/Ubuntu, included with Xcode CLT on macOS. On Windows, see INSTALL_WINDOWS.md.
Each step matters even though skipping one doesn't fail the build: without the dashboard build the dashboard returns 404, and without loomem-cli there is no stdio bridge for the Claude desktop app. The local embedding model is required: with the default embedding_provider = "local", the server refuses to start without it (refusing cloud fallback), with or without an API key. The default config also enables LLM-backed extraction and dreaming, so the server refuses to start unless an LLM key is set (export OPENAI_API_KEY=...) or LOOMEM_ALLOW_KEYLESS=1 is set. In keyless mode, memory_ingest returns a missing-key error and stores nothing, entity extraction is off, and dreaming fails; memory_store and search keep working.
Docker
docker build -t loomem .
export LOOMEM_AUTH_TOKEN=$(openssl rand -hex 32)
export LOOMEM_AT_REST_MASTER_KEY=$(openssl rand -base64 32)
export OPENAI_API_KEY="sk-..."
docker run -p 3030:3030 -v loomem-data:/data \
-e LOOMEM_AUTH_TOKEN -e LOOMEM_AT_REST_MASTER_KEY -e OPENAI_API_KEY \
-e LOOMEM_EMBEDDING_PROVIDER=openai -e LOOMEM_EMBEDDING_DIM=1536 loomem
Authentication is off by default only for local (loopback) runs. The Docker image binds 0.0.0.0, so the server requires LOOMEM_AUTH_TOKEN (refusing to start without it) and, by image default, an at-rest master key. Pass the key as Authorization: Bearer <key>. Deliberate opt-outs: LOOMEM_ALLOW_UNAUTH=1 (no auth) and LOOMEM_AT_REST_EXPECT_ENABLED=0 (plaintext at rest) — see docs/SECURITY.md.
The image contains no local embedding model, so the command switches embeddings to OpenAI (LOOMEM_EMBEDDING_PROVIDER=openai, LOOMEM_EMBEDDING_DIM=1536) and passes OPENAI_API_KEY. Stored text is then sent to the OpenAI API. Without these variables the server refuses to start (refusing cloud fallback).
Connect an MCP client
Loomem speaks MCP over streamable HTTP at /mcp. Any MCP-capable client works; recipes for the common ones:
Claude Code
claude mcp add --transport http loomem http://localhost:3030/mcp
Claude desktop app (and Cowork) — local stdio bridge
The Claude desktop app (and Cowork) connect to local MCP servers over stdio, not HTTP, and the "Add custom connector" box in Settings only accepts an https:// URL — so you cannot paste http://localhost:3030/mcp there. You bridge Loomem's local HTTP endpoint to stdio. Add one of the blocks below to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json), then fully restart Claude.
Recommended — native bridge, no Node (Loomem ≥ v0.2.1; the loomem-cli you already installed includes it):
{
"mcpServers": {
"loomem": {
"command": "/absolute/path/to/.loomem/bin/loomem-cli",
"args": ["mcp-stdio", "--url", "http://127.0.0.1:3030"]
}
}
}
Use the absolute path to loomem-cli (e.g. /Users/you/.loomem/bin/loomem-cli) — the desktop app doesn't inherit your shell PATH. Add "--token", "<your token>" to args, or set LOOMEM_AUTH_TOKEN in an "env" block, if you enabled auth.
Alternative — mcp-remote (works with any version, needs Node 18+ / npx):
{
"mcpServers": {
"loomem": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://127.0.0.1:3030/mcp", "--allow-http"]
}
}
}
--allow-http is required because the endpoint is plain HTTP on localhost. For auth, append "--header", "Authorization: Bearer ${LOOMEM_AUTH_TOKEN}" to args and add "env": { "LOOMEM_AUTH_TOKEN": "<your token>" }. Either block also works for any other stdio-only desktop client. (Claude Code is the exception — it speaks HTTP natively, so use the claude mcp add recipe above instead of a bridge.)
Claude — remote connector (HTTPS, hosted elsewhere)
To connect to a Loomem instance running on another machine, claude.ai/desktop's remote connector talks HTTPS. Expose your instance behind a reverse proxy with TLS (or a tunnel like Cloudflare Tunnel), set SERVER_ORIGIN=https://your-domain (required so OAuth metadata advertises the right URL), then add the connector in Claude settings pointing at https://your-domain/mcp. Loomem supports OAuth dynamic client registration out of the box (/.well-known/oauth-authorization-server).
ChatGPT — custom connector
ChatGPT requires HTTPS and OAuth for custom connectors (static API keys are not supported); developer mode must be enabled (Pro/Team/Enterprise plans). Expose the server over HTTPS as above, then: ChatGPT → Settings → Connectors → Add custom connector → paste https://your-domain/mcp and complete the OAuth flow.
OpenClaw
openclaw mcp add loomem --url http://localhost:3030/mcp --transport http \
--header "Authorization: Bearer $LOOMEM_AUTH_TOKEN"
For a remote OpenClaw gateway, point --url at your HTTPS endpoint instead.
Generic MCP client config
{
"mcpServers": {
"loomem": {
"type": "http",
"url": "http://localhost:3030/mcp",
"headers": { "Authorization": "Bearer <your LOOMEM_AUTH_TOKEN>" }
}
}
}
Standalone server notes
One Loomem instance can serve several clients at once (Claude Code locally, ChatGPT through the HTTPS endpoint, etc.) — they share the same context. Keep the bind address 127.0.0.1 unless you front it with TLS + auth; never expose the bare HTTP port to the internet.
Architecture
┌──────────────────────────────────────────────┐
│ loomem-server │
MCP client ──────► │ /mcp (JSON-RPC) ── dispatcher ─┐ │
HTTP client ─────► │ /v1/* + /api/* ─── handlers ───┤ │
└─────────────────────────────────┼────────────┘
▼
┌──────────────────────────────────────────────┐
│ loomem-core │
│ hybrid search (BM25 + vector + graph + RRF) │
│ consolidation / decay / dream workers │
│ entity extraction + alias graph │
│ encryption at rest (optional) │
└───────┬───────────────┬──────────────────────┘
▼ ▼
RocksDB Tantivy
(chunks, graph, (full-text index)
embeddings)
Workspace crates: loomem-core (engine), loomem-server (HTTP/MCP server), loomem-migrate (offline DB maintenance), loomem-cli (command-line client).
Documentation
- Quick start
- Configuration
- API reference
- MCP tools
- Architecture
- Deployment
- Security model
- Backup & restore
FAQ
What is Loomem? The open-source context layer for LLM agents. Written in Rust, it runs as a single binary on RocksDB and Tantivy and is served over the Model Context Protocol (MCP). It gives Claude, ChatGPT, Codex, or any MCP client the facts, decisions, and history they need to do real work for you — portable, local-first, and yours.
How is Loomem different from mem0, Zep, Letta, and cognee? Loomem ships as a single Rust binary with no external services — most alternatives need a separate vector and/or graph database. It leads on context ownership and portability, runs fully self-hosted and local-first, supports offline embeddings via local ONNX models, and is MCP-native out of the box.
Is Loomem free and open source? Yes — Apache-2.0, free to self-host. Source is in this repository.
Does Loomem require an internet connection or OpenAI?
No internet is required for core use. Embeddings can run on-device with a local ONNX model, and storing and searching context works fully offline. An OpenAI API key is needed only for the LLM-backed steps (memory_ingest extraction, consolidation, dream, contradiction detection); without it those steps are unavailable and the default config starts only with LOOMEM_ALLOW_KEYLESS=1, while memory_store and search keep working.
Which LLM clients can connect? Any MCP-capable client. Loomem speaks MCP over streamable HTTP and provides recipes for Claude, Claude Code, ChatGPT, Codex, and Cursor, plus OAuth dynamic client registration for remote connectors.
Why not just use ChatGPT or Claude built-in memory? Built-in memory is locked to one vendor. Loomem keeps your context portable across every tool and model, self-hosted and owned by you, with a structured entity graph and bitemporal history a single vendor's feature doesn't give you.
Author
Loomem is created and maintained by Łukasz Gumowski — [email protected].
License
Apache-2.0. See LICENSE.
