rivermind
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.
Install
git clone https://github.com/rivermind-ai/rivermind.git
cd rivermind
make install
source .venv/bin/activate
Quick start
rivermind 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 reachable
To wire this into Claude Desktop (three minutes from clone to Claude remembering what you told it), see the Claude Desktop quickstart.
Narrative synthesis (optional)
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.
Commands
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. |
Development
make install
make dev # run the server against a local dev DB
make test # pytest
make lint # ruff check + ruff format --check + mypy
Documentation
- Claude Desktop quickstart — connect Claude to a local Rivermind server.
- Architecture — system structure, updated as the code is written.
License
MIT — see LICENSE.
Code of Conduct
This project follows the Contributor Covenant v2.1.
1 maintainer
Metadata
1 maintainer
Release files for rivermind 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| rivermind-0.1.0.tar.gz | 53.8 kB | With provenance | Details for rivermind-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| rivermind-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for rivermind-0.1.0-py3-none-any.whl |
Total release size: 91.4 kB
Release files / rivermind-0.1.0.tar.gz
| Download URL | rivermind-0.1.0.tar.gz |
|---|---|
| Size | 53.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d7e1a51983425726fbb3b78197e05d1d5f4d76a946d9b0c465a5e457015e2bcb
|
|
BLAKE2b-256 checksum How to use checksums |
12c00e4b84e0c8526f944b79165bdc231a6b838dd212add5533d39c9f1411abf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 19, 2026.
Transparency logRelease files / rivermind-0.1.0-py3-none-any.whl
| Download URL | rivermind-0.1.0-py3-none-any.whl |
|---|---|
| Size | 37.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dae88e78c5fd0809d70bc2c0f356c7862ebcbe13677f93e4090d7c9e1e7e21e5
|
|
BLAKE2b-256 checksum How to use checksums |
69f955908ae9f7bd88160eea5ff97a504057c00b1f498bdeb73c114832fd468b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 19, 2026.
Transparency logSecurity for rivermind 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for rivermind-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
