Rivermind is a temporal memory layer for LLMs. It runs as a local MCP server over SQLite, stores bi-temporal observations (facts, events, reflections), and gives any MCP client cross-session recall without custom retrieval code.
git clone https://github.com/rivermind-ai/rivermind.git
cd rivermind
make install
source .venv/bin/activaterivermind init # creates ~/.rivermind/rivermind.db
rivermind serve # starts http://127.0.0.1:8080 (MCP at /mcp)
./scripts/smoke_claude.sh # verifies the server is reachableTo wire this into Claude Desktop (three minutes from clone to Claude remembering what you told it), see the Claude Desktop quickstart.
Rivermind records observations as you work and surfaces them in later conversations, with bi-temporal awareness of when something happened versus when it was learned.
Narratives require an LLM API key. Without one, serve and reeval still work: compaction and state rebuild run, synthesis is skipped with a warning.
Get a key from the provider of your choice:
- Anthropic: console.anthropic.com/settings/keys
- OpenAI: platform.openai.com/api-keys
Export it in your shell (default provider is Anthropic; set RIVERMIND_LLM_PROVIDER=openai if the key is an OpenAI one):
export RIVERMIND_API_KEY=sk-ant-... # or sk-... for OpenAI
export RIVERMIND_LLM_PROVIDER=anthropic # or "openai" (default: anthropic)To persist it across terminal sessions, append those two lines to ~/.zshrc (or ~/.bashrc) and source the file. Verify with echo $RIVERMIND_API_KEY.
All subcommands accept a global --db PATH (default ~/.rivermind/rivermind.db). Run rivermind --help for the full tree, or rivermind <command> --help for per-command flags.
| Command | Purpose |
|---|---|
rivermind init |
Create the DB and apply migrations. |
rivermind serve [--host] [--port] [--no-reeval] |
Run the FastAPI + MCP server. |
rivermind timeline [--start] [--end] [--topic] [--limit] [--json] |
Print observations in a time window. |
rivermind state [--subject] [--attribute] [--rebuild] [--json] |
Print state rows, or rebuild the projection. |
rivermind reeval |
Run narrative synthesis + compaction + state rebuild for overdue weeks. |
rivermind export --out PATH [--format json|sqlite] |
Dump observations, state, and narratives. |
rivermind import --from PATH |
Load a prior rivermind JSON export. |
make install
make dev # run the server against a local dev DB
make test # pytest
make lint # ruff check + ruff format --check + mypy- Claude Desktop quickstart — connect Claude to a local Rivermind server.
- Architecture — system structure, updated as the code is written.
MIT — see LICENSE.
This project follows the Contributor Covenant v2.1.