Installation Guide

Loomem ships as three self-contained binaries — loomem-server, loomem-cli, loomem-migrate — with RocksDB and Tantivy compiled in; they need only the system C and C++ runtime libraries. The local embedding model is a separate download. This guide covers every supported install path, verification, upgrades, and troubleshooting.

Supported platforms

Requirements for the installer: sh, tar, and curl or wget. No sudo — everything lands in your home directory.

Quick install

The repository is public, so the one-liner needs no authentication:

curl -fsSL https://raw.githubusercontent.com/vvooki-sys/loomem/main/install.sh | sh

The installer defaults to port 3030 and asks for a free one if it's taken; set LOOMEM_PORT=NNNN to pick a port non-interactively.

gh auth login            # once
gh api repos/<owner>/loomem/contents/install.sh -H "Accept: application/vnd.github.raw" | sh

export GH_TOKEN=ghp_xxx
curl -fsSL -H "Authorization: Bearer $GH_TOKEN" -H "Accept: application/vnd.github.raw" \
  https://api.github.com/repos/<owner>/loomem/contents/install.sh | sh

What the installer does

1. Detects OS and architecture (uname).
2. Picks a download source, first match wins: LOOMEM_BASE_URL mirror → GH_TOKEN/GITHUB_TOKEN (GitHub API) → logged-in gh CLI → public release URLs.
3. Resolves the latest release (or the tag pinned with LOOMEM_VERSION).
4. Downloads the platform archive and SHA256SUMS, verifies the checksum (hard failure on mismatch).
5. Installs the three binaries to ~/.loomem/bin.
6. Copies config templates (config.toml, entities.toml.example, synonyms.toml.example) to ~/.loomem and seeds entities.toml from the example (the server requires it at startup) — never overwrites existing files, so re-running is safe.
7. Prints PATH instructions if ~/.loomem/bin isn't on your PATH yet.

The installer does not download the local embedding model. Fetch it once before the first run.

Installer environment variables

Example — pin a version into a custom prefix:

LOOMEM_VERSION=v0.2.0 LOOMEM_INSTALL_DIR=/opt/loomem/bin sh install.sh

PATH setup

The installer doesn't modify your shell config. Add once:

echo 'export PATH="$HOME/.loomem/bin:$PATH"' >> ~/.zshrc   # or ~/.bashrc
exec $SHELL

First run

curl -fsSL https://raw.githubusercontent.com/vvooki-sys/loomem/main/scripts/fetch-embedding-model.sh | sh   # local embedding model, required
export OPENAI_API_KEY="sk-..."     # or: export LOOMEM_ALLOW_KEYLESS=1
cd ~/.loomem
loomem-server

The server refuses to start without the local embedding model (~113 MB, fetched once into ~/.loomem/models). With the default config it also needs an LLM key, or LOOMEM_ALLOW_KEYLESS=1 for keyless mode — see From source for what keyless mode turns off.

The server requires config.toml and entities.toml in its working directory — the installer seeds both, so running from ~/.loomem just works. Edit entities.toml to teach Loomem your people/projects/aliases (see the comments inside).

The server listens on http://127.0.0.1:3030 and stores data in ./data (relative to the working directory — running from ~/.loomem keeps data in ~/.loomem/data). Verify:

curl http://localhost:3030/health

Then connect an MCP client — recipes for Claude Code, claude.ai, ChatGPT, and OpenClaw are in the README.

Security: authentication is off by default, fine for localhost. If the server is reachable by anyone but you, set LOOMEM_AUTH_TOKEN (see SECURITY.md and deployment.md).

Verifying checksums manually

The installer verifies automatically, but to audit by hand:

gh release download v0.2.0 --repo vvooki-sys/loomem \
  --pattern 'loomem-0.2.0-aarch64-apple-darwin.tar.gz' --pattern 'SHA256SUMS'
shasum -a 256 -c --ignore-missing SHA256SUMS    # macOS
sha256sum -c --ignore-missing SHA256SUMS        # Linux

Upgrading

Re-run the installer — binaries are replaced, your config files are left untouched:

gh api repos/vvooki-sys/loomem/contents/install.sh -H "Accept: application/vnd.github.raw" | sh

Check the CHANGELOG for breaking changes first. If a release notes a storage-format migration, stop the server and run loomem-migrate before starting the new version.

Uninstalling

Loomem touches nothing outside its two directories:

rm -rf ~/.loomem          # binaries + config + data (if run from ~/.loomem)

Remove the PATH line from your shell config if you added one. If you ran the server from another working directory, its ./data lives there.

From source

git clone https://github.com/vvooki-sys/loomem.git
cd loomem
cp entities.toml.example entities.toml
(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 -p loomem-migrate
# binaries in target/release/

Requires Rust (stable), Node.js (for the dashboard) and libclang for the RocksDB build: apt install libclang-dev on Debian/Ubuntu; on macOS it ships with the Xcode Command Line Tools. On Windows, see INSTALL_WINDOWS.md.

Skipping the dashboard build leaves the dashboard returning 404. 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 may store the source text but returns a missing-key error and extracts no facts; 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

The image binds 0.0.0.0 and therefore requires an auth token and (by default) an at-rest master key — the server refuses to start without them. Deliberate opt-outs: LOOMEM_ALLOW_UNAUTH=1, LOOMEM_AT_REST_EXPECT_ENABLED=0. See deployment.md for reverse-proxy, TLS, and cloud options, and SECURITY.md for the security model.

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).

Troubleshooting