Mindcache

CLI

Install and use the Mindcache Rust runtime locally.

This page shows the shortest path to install the CLI and start using it locally.

Mindcache Memory CLI

Install

If you already have Rust installed:

source "$HOME/.cargo/env"
cd mindcache-memory
cargo install --path crates/memory-cli --bin mindcache-memory --force
mindcache-memory --help

If you do not have Rust yet:

curl https://sh.rustup.rs -sSf | sh
source "$HOME/.cargo/env"
cd mindcache-memory
cargo install --path crates/memory-cli --bin mindcache-memory --force
mindcache-memory --help

The binary is installed to:

~/.cargo/bin

If your shell cannot find it, add:

export PATH="$HOME/.cargo/bin:$PATH"

Current Runtime Model

The current runtime is tree-first:

  • core atom node types are only:

- fact - event - plan

  • source/material classification is:

- snippet - resource - writeup

  • import extracts atoms and stores source provenance
  • import does not build graph relations
  • daily digest reconciles atoms, writes daily writeups, and builds or updates the topic tree
  • the graph surface is now a secondary leaf-layer/debug view, not the primary memory structure

Quickstart

Initialize a database:

mindcache-memory init ./demo.sqlite3

Import text:

mindcache-memory import text "Met with a friend in Singapore to discuss a local-first memory runtime." ./demo.sqlite3

Run exact search over atoms:

mindcache-memory search exact "singapore runtime" ./demo.sqlite3 --limit 5

Run daily digest:

mindcache-memory digest daily ./demo.sqlite3

Run daily digest for a bounded batch of isolated atoms:

mindcache-memory digest daily ./demo.sqlite3 --batch-size 1 --json

Run daily digest for a single isolated atom:

mindcache-memory digest daily ./demo.sqlite3 --node-id <atom_id> --json

Inspect the current topic tree:

mindcache-memory inspect list topics ./demo.sqlite3 --json

Inspect daily writeups:

mindcache-memory inspect list daily-writeups ./demo.sqlite3 --json

Inspect the current leaf-layer graph/debug surface:

mindcache-memory inspect list graph ./demo.sqlite3 --min-importance 0.5

Inspect a single atom node plus its connected leaf-layer neighbors:

mindcache-memory inspect node <node_id> ./demo.sqlite3

Enable OpenRouter For Extraction And Digest

Extraction and digest both use the LLM-backed pipeline:

export OPENROUTER_API_KEY="<your_openrouter_key>"
export MINDCACHE_EXTRACTION_MODEL="openai/gpt-4.1-mini"
export MINDCACHE_DIGEST_MODEL="openai/gpt-4.1-mini"

Then run the same CLI commands as usual.

If OPENROUTER_API_KEY is not set, text and markdown ingest will fail instead of falling back to local heuristics.

Common Commands

Import markdown:

mindcache-memory import markdown ./notes/example.md ./demo.sqlite3

Import calendar:

mindcache-memory import calendar ./calendar/sample.ics ./demo.sqlite3

Update an editable text source:

mindcache-memory import update-text <source_id> "Updated source text" ./demo.sqlite3

Delete a source:

mindcache-memory import delete-source <source_id> ./demo.sqlite3

Delete an atom node:

mindcache-memory import delete-node <node_id> ./demo.sqlite3

Delete a topic subtree:

mindcache-memory import delete-topic <topic_id> ./demo.sqlite3

Search semantic:

mindcache-memory search semantic "local-first memory runtime" ./demo.sqlite3 --limit 5

Search topics:

mindcache-memory search topics "memory runtime" ./demo.sqlite3 --limit 10

Search the legacy/debug graph around a seed node:

mindcache-memory search graph <seed_node_id> ./demo.sqlite3 --hops 1 --limit 10

Inspect nodes:

mindcache-memory inspect list nodes ./demo.sqlite3 --json

Inspect sources:

mindcache-memory inspect list sources ./demo.sqlite3 --json

What Daily Digest Does Now

mindcache-memory digest daily now does three things in order:

  1. Reconciles the current day's atoms through the daily writeup surface
  2. In cold start, rebuilds the topic tree from all atoms
  3. After cold start, attaches isolated atoms into the existing topic tree through top-k topic search and local topic updates

Daily digest can now also be scoped:

  • --batch-size <n>

- only processes the first n currently isolated atoms

  • --node-id <atom_id>

- only processes that single isolated atom

This makes it possible to:

  • run one-atom debugging passes
  • chunk large digest workloads into repeatable batches
  • drive a resumable background digest worker from the same CLI

The digest result now reports fields like:

  • mode
  • atom_count
  • reconciled_atom_count
  • isolated_atom_count
  • topic_update_count
  • attached_atom_count
  • revised_topic_count
  • split_topic_count

The older graph_rebuild block is still present in the payload as a secondary debug surface, but it is no longer the main runtime model.

Command Surface

mindcache-memory init [db_path]
mindcache-memory migrate [db_path]
mindcache-memory migrate status [db_path]
mindcache-memory import markdown <source_path> [db_path]
mindcache-memory import text <content> [db_path]
mindcache-memory import calendar <source_path> [db_path]
mindcache-memory import update-text <source_id> <content> [db_path]
mindcache-memory import delete-source <source_id> [db_path]
mindcache-memory import delete-node <node_id> [db_path]
mindcache-memory import delete-topic <topic_id> [db_path]
mindcache-memory digest daily [db_path] [--node-id <id>] [--batch-size <n>] [--json]
mindcache-memory digest weekly [db_path]
mindcache-memory search exact <query> [db_path] [--type <node_type>] [--limit <n>]
mindcache-memory search semantic <query> [db_path] [--type <node_type>] [--limit <n>]
mindcache-memory search topics <query> [db_path] [--limit <n>]
mindcache-memory search graph <seed_node_id> [db_path] [--hops <n>] [--limit <n>]
mindcache-memory inspect list nodes [db_path]
mindcache-memory inspect list sources [db_path]
mindcache-memory inspect list topics [db_path]
mindcache-memory inspect list daily-writeups [db_path]
mindcache-memory inspect list graph [db_path] [--min-importance <0..1>]
mindcache-memory inspect node <node_id> [db_path]
mindcache-memory inspect topic <topic_id> [db_path]