mindloom

mindloom is a local-first memory system for AI assistants and tools.

It provides:

• mindloom-core: the cognitive memory engine (Rust library)
• mindloom-mcp: an MCP server and CLI binaries
• NPM installers for quick local setup

mindloom combines keyword recall, optional embedding/vector search, and a memory lifecycle model (short-term to long-term) so your assistant can retain and retrieve context over time.

Go Migration Scaffold

A Go workspace scaffold now exists under go/ to support an incremental Rust -> Go migration:

• go/core mirrors crates/mindloom-core
• go/mcp mirrors crates/mindloom-mcp
• go/cmd/* mirrors Rust binaries

Migration tracking artifacts live in docs/go-migration/.

MCP Feature Exposure Status

| Feature | Status | MCP exposure | |---------|--------|--------------| | Memory Dreams / Consolidation Scheduling | Partial | dream_scheduler (status, run_now, history) | | Reconsolidation | Partial | reconsolidate_memory (get, update) | | Memory Chains / Reasoning Paths | Partial | memory_chains (connections, path) |

Repository Layout

• crates/mindloom-core — core memory engine
• crates/mindloom-mcp — MCP server + CLI binaries
• packages/mindloom-mcp-npm — npm package that installs platform binaries
• packages/mindloom-init — setup helper CLI
• packages/mindloom-mcpb — MCP bundle artifacts/scripts
• tests/e2e — end-to-end and journey tests

Quick Start (from source)

Prerequisites

• Rust stable (1.80+ recommended)
• cargo
• Node.js 18+ (only needed for npm packages)

Build

cargo build --workspace

Run MCP server

cargo run -p mindloom-mcp --bin mindloom-mcp

Run CLI

cargo run -p mindloom-mcp --bin mindloom -- --help

Testing

cargo test --workspace --lib
cargo test -p mindloom-core
cargo test -p mindloom-mcp

Verification

go test ./go/internal/cli -run 'TestRunIngest(Success|WithMemoryTier|InvalidMemoryTier|MissingContent|InvalidNodeType|MissingDBPath)$' -count=1
go test ./go/mcp/internal/mcp -run 'TestToolsCallFallback(IngestSuccess|IngestMissingContent|IngestInvalidNodeType|IngestInvalidMemoryTier|SmartIngest|SessionCheckpoint|SessionCheckpointInvalidArgs)$' -count=1
go test ./go/core/storage -count=1
go test ./go/mcp/internal/mcp -count=1

Container Stack

The supported interoperable deployment path is Docker-first.

Start the semantic memory stack with:

docker compose -f docker/compose.semantic-stack.yml up --build

That stack brings up:

• embedding serving intfloat/multilingual-e5-large
• milvus as the vector database
• mindloom configured to use both services over the Compose network

Example smoke checks:

docker compose -f docker/compose.semantic-stack.yml run --rm mindloom health
docker compose -f docker/compose.semantic-stack.yml run --rm mindloom ingest "container memory" --memory-tier short_term
docker compose -f docker/compose.semantic-stack.yml run --rm mindloom stats
docker compose -f docker/compose.semantic-stack.yml exec -T embedding curl -fsS http://localhost/health
docker compose -f docker/compose.semantic-stack.yml exec -T reranker curl -fsS http://localhost/health

Full Docker semantic verification:

./scripts/verify-semantic-stack.sh

Observability UI (container-first):

docker compose -f docker/compose.semantic-stack.yml up --build mindloom-observability

Then open http://localhost:1420.

The UI runs fully in Docker and reads live data via the containerized backend API (mindloom-backend-api).

Optional desktop wrapper (still supported):

npm --prefix apps/mindloom-observability run tauri dev

Multi-brain examples:

docker compose -f docker/compose.semantic-stack.yml run --rm mindloom ingest "alpha memory" --agent-id agent-alpha --id alpha-1
docker compose -f docker/compose.semantic-stack.yml run --rm mindloom ingest "beta memory" --agent-id agent-beta --id beta-1
docker compose -f docker/compose.semantic-stack.yml run --rm mindloom backend run-once
docker compose -f docker/compose.semantic-stack.yml run --rm mindloom search --agent-id agent-alpha "alpha memory"

Optional:

• KEEP_STACK=1 ./scripts/verify-semantic-stack.sh keeps containers/volumes running for inspection
• TIMEOUT_SECONDS=900 ./scripts/verify-semantic-stack.sh increases readiness timeout for slower first downloads

If OpenSSL vendoring is slow in CI/local environments, you can prefer system OpenSSL:

OPENSSL_NO_VENDOR=1 cargo check -p mindloom-core -p mindloom-mcp

Installation (release binaries)

Download from GitHub Releases and extract the archive for your platform.

Example (Linux x64):

curl -L https://github.com/teraniq/mindloom/releases/latest/download/mindloom-mcp-x86_64-unknown-linux-gnu.tar.gz | tar -xz
./mindloom-mcp --help

Configuration

mindloom-mcp stores data in a local SQLite database (default app data directory). You can point it to a custom path with CLI flags where supported.

Milvus environment toggles are intentionally guarded until full backend support is available.

Recent enhancements

• OpenCode STM capture plugin (.opencode/plugins/mindloom-stm.ts) listens for chat.message/event hooks, captures assistant output plus reasoning metadata (when present), batches messages, and POSTs to Mindloom HTTP ingest (client_id, agent_alias, messages[]) without blocking chat flow.
• Dashboard tier visualization (crates/mindloom-mcp/src/dashboard.html) now displays STM/MTM/LTM cards, with the UI gracefully handling missing stmNodes, mtmNodes, or ltmNodes fields in the stats payload.

OpenCode plugin setup (repo-local)

1. Copy .opencode/plugins/mindloom-stm.config.example.json to .opencode/plugins/mindloom-stm.config.json and set endpoint.
2. Start the backend API with mindloom backend serve (default http://127.0.0.1:8787) or point endpoint to your deployed backend URL.
3. If your ingest endpoint requires auth, set MINDLOOM_INGEST_TOKEN and MINDLOOM_BACKEND_BEARER_TOKEN to the same value (or configure Basic auth via MINDLOOM_BACKEND_BASIC_AUTH_USER / MINDLOOM_BACKEND_BASIC_AUTH_PASS).
4. Load .opencode/plugins/mindloom-stm.ts from your OpenCode project plugin config.

Notes:

• client_id is generated deterministically from agent_alias and session context when available.
• If deterministic seed fields are missing, the plugin falls back to a persisted local ID at .opencode/plugins/.mindloom-stm-client-id.
• Reasoning payloads that are redacted ([REDACTED]) are skipped automatically.

Automated Build & Publish

This repo is prepared for automated publishing through GitHub Actions.

Workflows

• .github/workflows/test.yml — CI checks/tests
• .github/workflows/release-candidate.yml — manual RC tag flow with prerelease artifacts + npm rc publish
• .github/workflows/release.yml — cross-platform Go binary release artifacts (+ signatures/checksums)
• .github/workflows/publish.yml — release-event npm publish pipeline for stable latest releases
• docs/RELEASE_CHECKLIST.md — release runbook and validation checklist

Required GitHub Secrets

Set these in repository settings:

• CARGO_REGISTRY_TOKEN — crates.io API token
• NPM_TOKEN — npm automation token

Release flow

1. Update versions as needed (Cargo.toml / npm package manifests).
2. Create and push a tag like v1.3.0.
3. Publish a GitHub Release (or use workflow dispatch where available).
4. Actions will:
   • run checks/tests,
   • build release binaries,
   • verify stable npm package versions,
   • publish npm packages with rc dist-tag for release candidates and latest for stable releases.

License

Dual licensed where applicable under:

• MIT
• Apache-2.0

See individual crate/package manifests for exact licensing metadata.

Faster local Rust builds

This repository includes local build-speed defaults in .cargo/config.toml:

• linker auto-selection: mold when available, otherwise LLD,
• split-debuginfo=unpacked for separate DWARF files,
• CARGO_TARGET_DIR defaulting to /dev/shm/mindloom-target (tmpfs) when available,
• rustc-wrapper set to a script that uses sccache when installed.

For quickest test cycles, use:

./scripts/cargo-test-fast.sh

The script prefers nightly Cranelift (cargo +nightly test -Zcodegen-backend=cranelift) and falls back to regular cargo test if nightly is unavailable.

COPYRIGHT

• Frontend is done by Sam Vallad and is licensed under MIT
• Everything else is done by Teraniq LLC and is licensed under AGPL-3.0