trusty-memory

Machine-wide AI memory daemon built in Rust, using the Memory Palace architecture.

One install per machine. Multiple named palaces. Sub-5 ms baseline retrieval.

Getting Started

trusty-memory is a persistent background daemon that exposes memory tools to Claude Code over MCP. There are two ways to run it.

Path A: Standalone daemon (recommended)

Install once, run as a launchd service, and point Claude Code at it.

# 1. Install
cargo install trusty-memory

# 2. Install and start the launchd service (macOS)
trusty-memory service install

# 3. Add to your project's .mcp.json

.mcp.json in the project root:

{
  "mcpServers": {
    "trusty-memory": {
      "command": "trusty-memory",
      "args": ["serve", "--palace", "my-project"]
    }
  }
}

Palaces are created automatically on first use. No palace new step required.

For machine-wide config, use ~/.claude/mcp.json with the same contents.

Path B: Direct serve (no service install)

If you don't want a launchd service, just point Claude Code at serve directly. The daemon will auto-start on first MCP call and remain running until shut down.

{
  "mcpServers": {
    "trusty-memory": {
      "command": "trusty-memory",
      "args": ["serve", "--palace", "my-project"]
    }
  }
}

That's it. Claude Code now has 10 memory tools available.

Verifying

trusty-memory status
trusty-memory palace list

The Daemon Model

trusty-memory runs as a single long-lived process per machine. All projects share the same daemon; isolation is provided by palaces (named namespaces), not by separate processes.

• Auto-start. Every CLI command except serve, service, setup, and hooks calls ensure_daemon() first. If no daemon is alive, one is spawned detached and the command waits up to 5 seconds for it to come up.
• Service management (macOS). trusty-memory service install writes ~/Library/LaunchAgents/com.trusty.trusty-memory.plist and bootstraps it into the user's launchd domain. RunAtLoad: true, KeepAlive: true. On non-macOS platforms service returns an error pointing to systemd.
• HTTP port discovery. The daemon auto-binds starting at 127.0.0.1:3031 and walks up to 20 ports if that's taken. The chosen address is written to ~/Library/Application Support/trusty-memory/http_addr, which service status reads.
• Data directory. macOS: ~/Library/Application Support/trusty-memory/palaces/. Other platforms fall back to ~/.trusty-memory/palaces/.
• Logs. ~/.trusty-memory/logs/daemon.log. trusty-memory service logs tails the last 50 lines.
• Stdio-only mode. Pass --no-http to serve if you don't want a TCP listener. The daemon still writes its PID file but skips http_addr.
• Shutdown. trusty-memory stop reads the PID file and sends SIGTERM. Background dreamer tasks get a 2 second grace window before exit.

Full reference: docs/daemon.md.

Architecture

4-layer progressive retrieval

L0 and L1 are pre-cached in memory — reads never touch disk. L2 and L3 take a read lock on the vector index; many concurrent searches never block each other.

Dual store

• Vector index — usearch HNSW (all-MiniLM-L6-v2, 384-d, local ONNX). Handles semantic similarity search.
• Temporal knowledge graph — SQLite WAL. Stores subject-predicate-object triples with valid_from / valid_to intervals. Asserting a new fact automatically closes the prior active interval.

Palace hierarchy

Palace  (one per project or domain)
  └── Wing    (top-level domain: project area or agent persona)
        └── Room    (topic: Frontend / Backend / Testing / Planning / ...)
              └── Closet  (pre-computed pointer index: topic|entities -> drawer_ids)
                    └── Drawer  (atomic memory unit: text + importance + tags)

Background tasks

On startup, dreamer tasks run for each palace: memory consolidation, importance decay, and deduplication. They shut down cleanly within 2 seconds of SIGTERM.

CLI Reference

The commands you'll use day-to-day are bold.

MCP Tools

The MCP server exposes 10 tools:

When the server is launched with --palace <name>, the palace argument can be omitted from every tool call. Full JSON-RPC protocol, request/response examples, and error codes are in docs/mcp-stdio.md.

vs. kuzu-memory

kuzu-memory is a Python-based memory system built on the Kuzu graph database. Both projects solve overlapping problems with different trade-offs.

trusty-memory includes a (currently stub) read-only bridge to kuzu-memory databases for projects that already have one.

When to use each

• Use trusty-memory when you want a persistent, machine-wide daemon, multiple project namespaces under a single process, and always-available L0/L1 context without hitting a model.
• Use kuzu-memory when you want Python-ecosystem integration, per-project isolation with minimal setup, optional LLM reranking, and a simpler flat graph model.

Performance Targets

License

Elastic License 2.0 (ELv2).

Free to use for personal, internal, and commercial purposes. You may not provide this software to third parties as a hosted or managed service. See LICENSE for the full terms.