holetron-lab/fleet-memory
1
0
Fork 0
Code Releases Packages Activity Actions

docs: link the site, scope the fork comparison to the branch point, state the release status

Browse source
This commit is contained in:
RCLL 2026-08-24 07:49:45 +03:00
parent 9eb6784669
commit 509b759523
1 changed files with 69 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

90
README.md
View file

@ -8,6 +8,19 @@ RCLL is a fork of [`vectorize-io/hindsight`](https://github.com/vectorize-io/hin
RCLL is `recall` with the vowels dropped — the one operation every agent in the fleet performs before it does anything else. The tool is literally called `memory_recall`; the product is named after the call.
**Its one structural property worth remembering: the read path never invokes a language model.** A recall costs CPU and zero model tokens — see [architecture](https://rcll.ai/docs/architecture/).
### Status
The source is public and MIT. **There is no packaged release yet:** `rcll-mcp` is not published on npm and no container image is pushed. Running RCLL today means building from this tree, which the quick start below does. Don't quote an install command as working until [rcll.ai](https://rcll.ai/) shows one.
| | |
|---|---|
| Site, measured numbers | [rcll.ai](https://rcll.ai/) · [benchmarks](https://rcll.ai/docs/benchmarks/) |
| Written for an AI agent, not a human | [rcll.ai/agents.md](https://rcll.ai/agents.md) |
| Where we branched from upstream, and how to take the next release | [FORK.md](./FORK.md) |
| Architecture spec | [RCLL.md](./RCLL.md) |
---
## How it works
@ -47,20 +60,38 @@ RCLL is `recall` with the vowels dropped — the one operation every agent in th
**Tunnels** — cross-bank bridges between agents. Agent A discovers an insight — Agent B sees it through a tunnel without data duplication.
## Comparison
## What this fork adds
| | [Hindsight](https://github.com/vectorize-io/hindsight) (upstream) | **RCLL** |
This is a list of **our additions relative to our branch point** ([`d054b884`](https://github.com/vectorize-io/hindsight/commit/d054b884), April 2026) — not a claim about what upstream Hindsight does today. Upstream has shipped roughly 1,700 commits and four minor releases since we branched; assume anything below has an upstream answer we have not evaluated, and read [FORK.md](./FORK.md) before treating this as a comparison.
| Added here | What it is |
|---|---|
| **Rooms** | Per-agent and shared scoping on every write and every read |
| **Halls** | Knowledge typing within a room (fact, event, decision, procedure, warning) |
| **Layers L0–L3** | Durability tiers; L0 always recalled, L3 deep-search only |
| **Classification** | Keyword-based, sub-millisecond, **no LLM call** — the taxonomy costs zero tokens |
| **Closets** | Compressed summaries by room + hall, with pointers back to sources |
| **Tunnels** | Cross-bank bridges |
| **MCP server** | Standalone server exposing 5 tools over MCP |
Everything is additive: the upstream `/retain` and `/recall` contracts as of our branch point still work unchanged, and every new parameter is optional.
## Measured
Retrieval quality, our own models on the public LoCoMo dataset, using a third-party harness rather than one we wrote. Full method, the arms that lost, and the caveats: [rcll.ai/docs/benchmarks/](https://rcll.ai/docs/benchmarks/).
| Configuration | nDCG@10 | vs BM25 |
|---|---|---|
| **What it is** | Long-term memory store | Storage + taxonomy hybrid |
| **Storage** | Vector store + embeddings | Vector store + embeddings |
| **Memory structure** | Flat (all memories equal) | Rooms → Halls → Layers + embeddings |
| **Retrieval** | Semantic search | Room-scoped semantic search |
| **Classification** | None | Keyword-based, <1ms, zero LLM cost |
| **Priority tiers** | All memories equal | L0–L3 (implemented) |
| **Compression** | None | Closets with source pointers |
| **Multi-agent** | Shared bank | Tunnels (cross-bank bridges) |
| **MCP integration** | API only | **5 tools via MCP protocol** |
| **Setup** | Docker | Docker (drop-in upgrade) |
| BM25 | 0.3885 | baseline |
| vector | 0.4244 | +0.036 |
| hybrid fusion | 0.4722 | +0.084 |
| **hybrid fusion + reranker** (default) | **0.5862** | **+0.198** |
**This is retrieval quality, not answer accuracy.** It is not comparable to figures of the form "77% on LoCoMo", which measure a reader and a judge on top of a store. We publish no accuracy number because we have not run a reader and a judge.
Two results that go against us are on the benchmarks page rather than left out: on multi-hop questions our default fusion is **worse** than vector-plus-reranker, and on single-hop BM25 alone beats dense retrieval.
Latency on CPU with no GPU: ~0.29 s for search, ~3.0 s including the cross-encoder reranker. The reranker is 85% of the time and the single largest quality gain we can measure.
## Quick start
@ -72,7 +103,9 @@ cp .env.example .env
docker compose -f docker-compose.rcll.yml up -d
```
API available at `http://localhost:5100`. Drop-in replacement for vanilla Hindsight — same API, same clients, new brain.
This **builds the image from this tree** — there is no published image to pull, so the first run compiles and is not fast. The API then listens on `http://localhost:5100`.
Clients written against upstream Hindsight's API as of our branch point keep working — the added parameters are optional. It is *not* a drop-in for current upstream Hindsight, which is several releases ahead of this fork.
### Embeddings
@ -86,6 +119,10 @@ HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL=BAAI/bge-m3 # 1024-dim, multilingual
Dimension is detected automatically. ⚠️ Switching models changes the vector dimension — do it on an **empty** memory store, or wipe + re-embed, since existing vectors can't be mixed across dimensions.
### Running without an LLM key
`LLM_PROVIDER=none` is a supported configuration, and it is a smaller product rather than the same one for free: retain drops to chunk mode — chunks stored and embedded whole, with **no fact extraction, no entity resolution, no causal links**, and consolidation and reflection off. You get a hybrid vector-and-lexical chunk store. Reading is unaffected, because reading never calls a model anyway. Choose this deliberately, or point extraction at a local model — don't arrive here by leaving a field blank.
## MCP Server
The `mcp-server/` directory contains a standalone [MCP](https://modelcontextprotocol.io) server. Any MCP-compatible client (Claude Code, OpenClaw, Cursor, etc.) connects and gets structured long-term memory.
@ -100,6 +137,8 @@ The `mcp-server/` directory contains a standalone [MCP](https://modelcontextprot
| `memory_compress` | Create closet summaries from accumulated facts |
| `memory_bridge` | Cross-bank tunnels between related memories |
`memory_recall` is the only one of the five that never calls a model. `memory_reflect` is an agentic loop with repeated LLM calls — if you expose this server to anything untrusted, expose `memory_recall` alone.
### Setup
```bash
@ -134,7 +173,7 @@ See [`mcp-server/README.md`](./mcp-server/README.md) for full docs and environme
## API changes from upstream
The base `/retain` and `/recall` endpoints are fully backward-compatible. New parameters are optional.
The base `/retain` and `/recall` endpoints are backward-compatible with upstream as of our branch point. New parameters are optional.
### New parameters
@ -191,7 +230,7 @@ curl -X POST http://localhost:5100/retain \
-H "Content-Type: application/json" \
-d '{
"bank": "project-alpha",
"text": "Never restart PROD PM2 without confirming DEV works first.",
"text": "Never restart PROD without confirming staging works first.",
"room": "deployment",
"hall": "warning",
"layer": 0
@ -225,6 +264,15 @@ curl -X POST http://localhost:5100/bridge \
}'
```
## Known limits
Honest list, kept here rather than only on the site:
- **You cannot export your memory yet.** The upstream `export` command emits a bank *template* — config, mental models, directives — and none of your stored content. A full dump that carries rooms, halls, layers and the link graph is the top item on our list, because it is the one thing that should not be missing from a store you self-host.
- **No accuracy benchmark.** Retrieval quality is measured and published; a reader-and-judge run is not.
- **Adversarial / unanswerable questions** — where the right answer is "I don't know" — are not covered by the retrieval metric we report, and that is the category most likely to embarrass us.
- **Switching `MEMORY_MODE` later does not migrate what you already stored.** Pick before you accumulate.
## What we changed
A taxonomy layer over Hindsight's vector store, plus a standalone MCP server.
@ -238,19 +286,19 @@ Key additions:
- Compression — closet generation with source linking
- Tunnels — cross-bank memory sharing protocol
Full architectural spec: [RCLL.md](./RCLL.md)
Full architectural spec: [RCLL.md](./RCLL.md). Commit-by-commit account of the fork: [FORK.md](./FORK.md).
## Upstream compatibility
## Upstream
This fork tracks `vectorize-io/hindsight` as upstream. To pull updates:
This fork branches from [`d054b884`](https://github.com/vectorize-io/hindsight/commit/d054b884) and its changes are a readable series on top of that commit, so taking a new upstream release is a rebase rather than an excavation:
```bash
git remote add upstream https://github.com/vectorize-io/hindsight.git
git fetch upstream
git merge upstream/main
git fetch upstream --tags
git rebase --onto <upstream-tag> d054b884 main
```
All changes are additive — existing Hindsight behavior is preserved.
Expect real conflicts: the rooms work touches the same engine files upstream has rewritten most. [FORK.md](./FORK.md) lists which ones and why.
## Credits