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

brand: Hindsight-MemPalace -> RCLL

Browse source 
Recovered from the 2026-06-27 snapshot import by classifying the base..snapshot delta at line granularity. Upstream base: d054b884 (2026-04-10).
This commit is contained in:
RCLL 2026-08-23 23:50:04 +03:00
parent d2f74c5126
commit eea8d0f2a0
2 changed files with 423 additions and 251 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

223
RCLL.md Normal file
View file

@ -0,0 +1,223 @@
# RCLL Architecture
> Hierarchical memory system extending Hindsight. Based on ADR-145 design spec.
## Overview
RCLL adds spatial organization to Hindsight's flat memory bank. Every memory unit gets classified into a **Room** (topic) and **Hall** (knowledge type), assigned a **Layer** (priority 0-3), and optionally linked via **Tunnels** (cross-bank bridges) or compressed into **Closets** (summaries).
The result is a navigable, priority-aware memory structure that replaces flat vector search with structured recall — without breaking any existing Hindsight behavior.
## Core Concepts
### Rooms (Topics)
Rooms represent topical areas. Each memory is classified into exactly one room.
| Room | Description |
|---|---|
| `auth` | Authentication, authorization, tokens, sessions |
| `pipeline` | CI/CD, build pipelines, automation chains |
| `infrastructure` | Servers, networking, hardware, OS-level config |
| `deployment` | Deploy procedures, rollbacks, release management |
| `schema` | Database schema, migrations, data models |
| `api` | API endpoints, contracts, integrations |
| `ui` | Frontend, components, layout, styling |
| `tax` | Tax calculations, fiscal rules, reporting |
| `hr` | Human resources, hiring, onboarding |
| `legal` | Legal requirements, contracts, terms |
| `compliance` | Regulatory compliance, audits, certifications |
| `monitoring` | Logs, alerts, metrics, observability |
| `agent` | AI agents, tools, prompts, agent behavior |
| `general` | Fallback for unclassified memories |
### Halls (Knowledge Types)
Halls categorize the nature of knowledge. Each memory belongs to exactly one hall.
| Hall | Description |
|---|---|
| `warning` | Things to avoid, dangers, prohibitions |
| `decision` | Choices made, approvals, rejections |
| `procedure` | How-to, step-by-step processes |
| `event` | Things that happened — incidents, releases, milestones |
| `preference` | Likes, favorites, style choices |
| `discovery` | Findings, insights, research results |
| `fact` | General factual statements (default) |
### Layers (Priority L0-L3)
Layers control recall priority. Lower number = higher priority.
| Layer | Name | Behavior | Example |
|---|---|---|---|
| **L0** | Critical | Must always be recalled | "Never delete production DB" |
| **L1** | Important | High relevance, recalled by default | "Deploy requires DEV test first" |
| **L2** | Normal | Standard facts (default for new memories) | "API uses JWT auth" |
| **L3** | Archive | Low priority, only recalled when specifically requested | "Old endpoint deprecated in v2" |
### Tunnels (Cross-Bank Bridges)
Tunnels connect memory units across different banks, enabling cross-context recall. A tunnel is a directed link between two memory units in separate banks, with optional metadata describing the relationship.
Use cases:
- A deployment procedure in one bank linked to an incident report in another
- A schema decision linked to the API change it motivated
- A warning in a project bank linked to the same warning in a team bank
Tunnels are bidirectional by default — creating a tunnel from A to B also makes B discoverable from A.
### Closets (Compressed Summaries)
Closets are AI-generated summaries of groups of related memories. They reduce noise in recall by consolidating repetitive or related facts into a single summary unit.
Each closet stores:
- The compressed summary text
- A vector embedding for search
- References to the source memory units it was built from
- The room and hall inherited from the source group
Closets are created on demand (via API) or automatically when a room exceeds a configurable memory count threshold.
## Database Schema Changes
### Modified: `memory_units` table
Added columns:
```sql
ALTER TABLE memory_units ADD COLUMN room VARCHAR(64) DEFAULT 'general';
ALTER TABLE memory_units ADD COLUMN hall VARCHAR(64) DEFAULT 'fact';
ALTER TABLE memory_units ADD COLUMN layer INTEGER DEFAULT 2;
```
### New table: `tunnels`
Stores cross-bank links with metadata.
```sql
CREATE TABLE tunnels (
id UUID PRIMARY KEY,
source_unit_id UUID REFERENCES memory_units(id),
target_unit_id UUID REFERENCES memory_units(id),
source_bank_id UUID REFERENCES memory_banks(id),
target_bank_id UUID REFERENCES memory_banks(id),
relationship VARCHAR(256),
created_at TIMESTAMP DEFAULT NOW()
);
```
### New table: `closets`
Stores compressed summaries with embeddings.
```sql
CREATE TABLE closets (
id UUID PRIMARY KEY,
bank_id UUID REFERENCES memory_banks(id),
room VARCHAR(64),
hall VARCHAR(64),
summary TEXT NOT NULL,
embedding VECTOR(1536),
source_unit_ids UUID[],
created_at TIMESTAMP DEFAULT NOW()
);
```
### Migration
File: `aa1_add_room_hall_to_memory_units.py`
Applies all three schema changes (columns + tables) in a single migration. Existing memory units get default values (`room='general'`, `hall='fact'`, `layer=2`).
## Auto-Classification
The `room_hall_classifier.py` module classifies memories using keyword regex patterns. No LLM call is needed — this keeps classification fast and deterministic.
**Algorithm:**
1. Run memory text against `ROOM_PATTERNS` — first match wins, set room
2. Run memory text against `HALL_PATTERNS` — first match wins, set hall
3. If no match: fall back to `room="general"`, `hall="fact"`
**To extend classification:** add patterns to `ROOM_PATTERNS` or `HALL_PATTERNS` lists in `room_hall_classifier.py`. Patterns are evaluated in order, so place more specific patterns before general ones.
## API Extensions
### Retain — `POST /banks/{bank_id}/retain`
New optional fields in request body:
| Field | Type | Default | Description |
|---|---|---|---|
| `room` | string | auto-classified | Override auto-classification for room |
| `hall` | string | auto-classified | Override auto-classification for hall |
| `layer` | integer | `2` | Priority level 0-3 |
If `room` or `hall` are omitted, the auto-classifier assigns them. If provided, the explicit value takes precedence.
### Recall — `GET /banks/{bank_id}/recall`
New optional query parameters:
| Param | Type | Default | Description |
|---|---|---|---|
| `room` | string | — | Filter results by room |
| `hall` | string | — | Filter results by hall |
| `max_layer` | integer | — | Only return memories with layer <= this value |
These filters are applied after vector search, narrowing results from the ranked candidates.
### New Endpoints
#### `POST /bridge`
Create a cross-bank memory bridge (convenience wrapper around tunnels).
#### `GET /tunnels`
List all tunnels, optionally filtered by bank.
#### `POST /tunnels`
Create a tunnel linking two memory units across banks.
Request body:
```json
{
"source_unit_id": "uuid",
"target_unit_id": "uuid",
"relationship": "optional description"
}
```
#### `GET /closets`
List closets, optionally filtered by bank, room, or hall.
#### `POST /closets`
Create a closet (AI-compressed summary) from a set of memory units.
Request body:
```json
{
"bank_id": "uuid",
"source_unit_ids": ["uuid", "uuid"],
"room": "optional",
"hall": "optional"
}
```
The summary is generated by the AI and stored with a vector embedding for future recall.
## Files Modified
11 files modified from upstream, 2 new files added. See `README.md` for the full list.
Key files:
- `room_hall_classifier.py` — auto-classification logic (new)
- `aa1_add_room_hall_to_memory_units.py` — database migration (new)
- Retain/recall endpoints — extended with room/hall/layer support
- Tunnel and closet endpoints — new route handlers
## Design Principles
1. **Additive-only changes** — upstream Hindsight compatibility is fully preserved. No existing behavior is altered; all new fields are optional.
2. **No LLM calls for classification** — keyword heuristics keep classification fast, cheap, and deterministic. LLM is only used for closet summary generation.
3. **Optional parameters** — all new fields default to sensible values. Existing API consumers work unchanged without modification.
4. **Extensible taxonomy** — rooms and halls are soft-coded via pattern lists in the classifier, not hardcoded enums. Adding a new room or hall is a one-line pattern addition.

451
README.md
View file

@ -1,313 +1,262 @@
<div align="center"> # RCLL
![Hindsight Banner](./hindsight-docs/static/img/hindsight-github-banner.png) **Self-hosted shared memory for a _team_ of AI agents. Storage + structure in one system.**
[Documentation](https://hindsight.vectorize.io) • [Paper](https://arxiv.org/abs/2512.12818) • [Cookbook](https://hindsight.vectorize.io/cookbook) • [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup) > RCLL — team memory for agent fleets. Built on Hindsight (github.com/vectorize-io/hindsight, MIT).
[![CI](https://github.com/vectorize-io/hindsight/actions/workflows/release.yml/badge.svg)](https://github.com/vectorize-io/hindsight/actions/workflows/release.yml) RCLL is a fork of [`vectorize-io/hindsight`](https://github.com/vectorize-io/hindsight) (MIT). It keeps Hindsight's storage engine and adds **rooms** — shared, isolated memory across a team of agents — plus a hierarchical depth model (L0–L3). The room/hall/layer taxonomy is prior art in the hierarchical-memory space; the implementation here is our own.
[![Slack Community](https://img.shields.io/badge/Slack-Join%20Community-4A154B?logo=slack)](https://join.slack.com/t/hindsight-space/shared_invite/zt-3nhbm4w29-LeSJ5Ixi6j8PdiYOCPlOgg)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![gitcgr](https://gitcgr.com/badge/vectorize-io/hindsight.svg)](https://gitcgr.com/vectorize-io/hindsight)
![PyPI - Downloads](https://img.shields.io/pypi/dm/hindsight-api?label=PyPI)
![NPM Downloads](https://img.shields.io/npm/dm/%40vectorize-io%2Fhindsight-client?logoColor=orange&label=NPM&color=blue&link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2F%40vectorize-io%2Fhindsight-client)
<br/>
<a href="https://trendshift.io/repositories/15603" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15603" alt="vectorize-io%2Fhindsight | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a> 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.
</div>
--- ---
## What is Hindsight? ## How it works
Hindsight™ is an agent memory system built to create smarter agents that learn over time. Most agent memory systems focus on recalling conversation history. Hindsight is focused on making agents that learn, not just remember. ```
┌──────────────────────────────────────────────────────┐
│ RCLL │
│ │
│ ┌─── Room: auth ───┐ ┌─── Room: pipeline ──┐ │
│ │ Hall: facts │ │ Hall: decisions │ │
│ │ Hall: procedures │ │ Hall: events │ │
│ │ Hall: warnings │ │ Hall: facts │ │
│ │ │ │ │ │
│ │ L0 ████ always │ │ L0 ████ always │ │
│ │ L1 ███░ warm │ │ L1 ███░ warm │ │
│ │ L2 ██░░ cold │ │ L2 ██░░ cold │ │
│ │ L3 █░░░ archive │ │ L3 █░░░ archive │ │
│ └──────────────────┘ └─────────────────────┘ │
│ │ │ │
│ └──── Tunnel ──────────┘ │
│ (cross-bank bridge) │
│ │
│ Closets: compressed summaries + source pointers │
└──────────────────────┬───────────────────────────────┘
│
Hindsight vector store
(embeddings + semantic search)
```
**Rooms** — topic isolation. Auth, pipeline, infrastructure, schema — each topic in its own room. An agent searching for auth facts won't wade through 500 deploy memories.
<video src="https://github.com/user-attachments/assets/923b798d-3581-4897-bb62-9cfa5a931682" controls></video> **Halls** — knowledge typing within a room. Fact, event, decision, procedure, warning. The system knows *what* it's looking at before reading — like `Content-Type` for memory.
It eliminates the shortcomings of alternative techniques such as RAG and knowledge graph and delivers state-of-the-art performance on long term memory tasks. **Layers L0–L3** — four priority tiers. L0 (core) is always loaded. L3 (archive) is deep-search only. Same idea as CPU cache hierarchy: L1 is fast and small, RAM is slow but holds everything.
## Memory Performance & Accuracy **Closets** — AI-compressed summaries with source pointers. Deduplication at the knowledge level: 10 related facts → 1 paragraph + references.
Hindsight is the most accurate agent memory system ever tested according to benchmark performance. It has achieved state-of-the-art performance on the LongMemEval benchmark, widely used to assess memory system performance across a variety of conversational AI scenarios. The current reported performance of Hindsight and other agent memory solutions as of January 2026 is shown here: **Tunnels** — cross-bank bridges between agents. Agent A discovers an insight — Agent B sees it through a tunnel without data duplication.
![Overview](./hindsight-docs/static/img/hindsight-bench.jpg) ## Comparison
The benchmark performance data for Hindsight has been independently reproduced by research collaborators at the Virginia Tech [Sanghani Center for Artificial Intelligence and Data Analytics](https://sanghani.cs.vt.edu/) and The Washington Post. Other scores are self-reported by software vendors. | | [Hindsight](https://github.com/vectorize-io/hindsight) (upstream) | **RCLL** |
|---|---|---|
| **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) |
Hindsight is being used in production at Fortune 500 enterprises and by a growing number of AI startups. ## Quick start
## Adding Hindsight to Your AI Agents
The easiest way to use Hindsight with an existing agent is with the LLM Wrapper. You can add memory to your agent with 2 lines of code. That will swap your current LLM client out with the Hindsight wrapper. After that, memories will be stored and retrieved automatically as you make LLM calls.
If you need more control over how and when your agent stores and recalls memories, there's also a simple API you can integrate with using the SDKs or directly via HTTP.
![Hindsight Banner](./hindsight-docs/static/img/migration-code.png)
---
> 🤖 **Using a coding agent?** Install the Hindsight documentation skill for instant access to docs while you code:
> ```bash
> npx skills add https://github.com/vectorize-io/hindsight --skill hindsight-docs
> ```
> Works with Claude Code, Cursor, and other AI coding assistants.
---
## Quick Start
### Docker (recommended)
```bash ```bash
export OPENAI_API_KEY=sk-xxx git clone https://github.com/holetron-lab/rcll.git
cd rcll
docker run --rm -it --pull always -p 8888:8888 -p 9999:9999 \ cp .env.example .env
-e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \ # edit .env with your config
-v $HOME/.hindsight-docker:/home/hindsight/.pg0 \ docker compose -f docker-compose.rcll.yml up -d
ghcr.io/vectorize-io/hindsight:latest
``` ```
>API: http://localhost:8888 API available at `http://localhost:5100`. Drop-in replacement for vanilla Hindsight — same API, same clients, new brain.
>UI: http://localhost:9999
You can modify the LLM provider by setting `HINDSIGHT_API_LLM_PROVIDER`. Valid options are `openai`, `anthropic`, `gemini`, `groq`, `ollama`, `lmstudio`, and `minimax`. The documentation provides more details on [supported models](https://hindsight.vectorize.io/developer/models). ### Embeddings
Ships with `BAAI/bge-small-en-v1.5` (384-dim) — fast, CPU-friendly, baked into the image so first run needs no network download. It's **English-optimized**; recall quality on other languages degrades.
For multilingual memory (e.g. RU, multi-script), point it at a multilingual model:
### Docker (external PostgreSQL)
```bash ```bash
export OPENAI_API_KEY=sk-xxx HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL=BAAI/bge-m3 # 1024-dim, multilingual
export HINDSIGHT_DB_PASSWORD=choose-a-password
cd docker/docker-compose
docker compose up
``` ```
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.
>API: http://localhost:8888 ## MCP Server
>UI: http://localhost:9999
### Client 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.
### Tools
| Tool | Description |
|------|-------------|
| `memory_retain` | Save a memory with automatic room/hall classification |
| `memory_recall` | Scoped semantic search with room/hall/layer filters |
| `memory_reflect` | Deep reasoning — synthesize facts, find patterns, answer with citations |
| `memory_compress` | Create closet summaries from accumulated facts |
| `memory_bridge` | Cross-bank tunnels between related memories |
### Setup
```bash ```bash
pip install hindsight-client -U cd mcp-server
# or npm install
npm install @vectorize-io/hindsight-client RCLL_URL=http://localhost:5100 node server.js
``` ```
#### Python ### Claude Code config
```python Add to `~/.claude/mcp.json`:
from hindsight_client import Hindsight
client = Hindsight(base_url="http://localhost:8888") ```json
{
# Retain: Store information "mcpServers": {
client.retain(bank_id="my-bank", content="Alice works at Google as a software engineer") "rcll": {
"command": "node",
# Recall: Search memories "args": ["/path/to/mcp-server/server.js"],
client.recall(bank_id="my-bank", query="What does Alice do?") "env": {
"RCLL_URL": "http://localhost:5100",
# Reflect: Generate disposition-aware response "RCLL_BANK": "my-agent-bank"
client.reflect(bank_id="my-bank", query="Tell me about Alice") }
``` }
}
#### Node.js / TypeScript
```bash
npm install @vectorize-io/hindsight-client
```
```javascript
const { HindsightClient } = require('@vectorize-io/hindsight-client');
const main = async () => {
const client = new HindsightClient({ baseUrl: 'http://localhost:8888' });
await client.retain('my-bank', 'Alice loves hiking in Yosemite');
const results = await client.recall('my-bank', 'What does Alice like?');
console.log(results);
} }
main();
``` ```
Upgrading from the old package name? `HINDSIGHT_URL` and the legacy bank variable are still read
as a fallback, so an existing config keeps working — it just prints a deprecation notice on start.
### Python Embedded (no server required) See [`mcp-server/README.md`](./mcp-server/README.md) for full docs and environment variables.
## API changes from upstream
The base `/retain` and `/recall` endpoints are fully backward-compatible. New parameters are optional.
### New parameters
| Endpoint | Parameter | Type | Description |
|----------|-----------|------|-------------|
| `/retain` | `room` | string | Topic room (auto-classified if omitted) |
| `/retain` | `hall` | string | Knowledge type (auto-classified if omitted) |
| `/retain` | `layer` | int | Priority 0-3 (default: 2) |
| `/recall` | `room` | string | Filter recall to a specific room |
| `/recall` | `hall` | string | Filter recall to a specific hall |
| `/recall` | `max_layer` | int | Maximum layer depth to search |
### New endpoints
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/bridge` | Create a cross-bank memory bridge |
| GET | `/tunnels` | List existing tunnels |
| POST | `/tunnels` | Create a tunnel between banks |
| GET | `/closets` | List compressed memory summaries |
| POST | `/closets` | Compress L3 memories into a closet |
## Room/Hall taxonomy
### Rooms (topics)
`auth` · `pipeline` · `infrastructure` · `deployment` · `schema` · `api` · `ui` · `tax` · `hr` · `legal` · `compliance` · `monitoring` · `agent` · `general`
### Halls (knowledge types)
`warning` · `decision` · `procedure` · `event` · `preference` · `discovery` · `fact`
### Layers
| Layer | Name | Behavior |
|-------|------|----------|
| **L0** | Critical | Always recalled |
| **L1** | Important | Recalled by default |
| **L2** | Normal | Standard (default for new memories) |
| **L3** | Archive | Deep search only, compressed into closets |
## Auto-classification
RCLL includes a keyword-based classifier (`room_hall_classifier.py`) that assigns room and hall automatically when not provided. No LLM call — classification is instant and free.
Extensible: add keywords to `ROOM_KEYWORDS` / `HALL_KEYWORDS` dictionaries.
## Examples
### Store a memory
```bash ```bash
pip install hindsight-all -U 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.",
"room": "deployment",
"hall": "warning",
"layer": 0
}'
``` ```
```python ### Scoped recall
import os
from hindsight import HindsightServer, HindsightClient
with HindsightServer( ```bash
llm_provider="openai", curl -X POST http://localhost:5100/recall \
llm_model="gpt-5-mini", -H "Content-Type: application/json" \
llm_api_key=os.environ["OPENAI_API_KEY"] -d '{
) as server: "bank": "project-alpha",
client = HindsightClient(base_url=server.url) "query": "deployment safety rules",
client.retain(bank_id="my-bank", content="Alice works at Google") "room": "deployment",
results = client.recall(bank_id="my-bank", query="Where does Alice work?") "hall": "warning",
"max_layer": 1
}'
``` ```
### Cross-bank bridge
--- ```bash
curl -X POST http://localhost:5100/bridge \
## Use Cases -H "Content-Type: application/json" \
-d '{
"source_bank": "project-alpha",
Hindsight is built to support conversational AI agents as well as agents that are intended to perform tasks autonomously. The ideal use case for Hindsight are agents that require a blend of these features such as AI employees that need to handle open-ended tasks, change behavior based on user feedback, and learn to perform complex tasks to automate work at a level that approximates a human work. Hindsight can be used with simple AI workflows like those built with n8n and other similar tools, but may be overkill for such applications. "target_bank": "project-beta",
"room": "infrastructure",
### Per-User Memories and Chat History "hall": "procedure"
}'
One of the simpler use cases you can use Hindsight for is to personalize AI chatbots and other conversational agents by storing and recalling memories associated with individual users.
The requirements for this use case usually look something like this:
![Per-User Memories](./hindsight-docs/static/img/per-user-memory-requirements.png)
<video src="https://github.com/user-attachments/assets/4805e8e1-e7d1-47c6-a4f8-2344a5ec8906" controls></video>
Satisfying these requirements in Hindsight is straightforward. When new user inputs and tool calls are ingested into Hindsight using the retain operation, custom metadata can be used to enrich the new memories. Metadata provides a convenient way to isolate memories that need to be restricted to a given user. Once these are fed into the retain operation, any raw memories and mental models that get created can be filtered when retrieving relevant memories.
![Per-User Memories](./hindsight-docs/static/img/per-user-memory-howto.png)
---
## Architecture & Operations
![Overview](./hindsight-docs/static/img/hindsight-overview.webp)
Most agent memory implementations rely on basic vector search or sometimes use a knowledge graph. Hindsight uses biomimetic data structures to organize agent memories in a way that is more like how human memory works:
- **World:** Facts about the world ("The stove gets hot")
- **Experiences:** Agent's own experiences ("I touched the stove and it really hurt")
- **Mental Models:** Learned understanding of the agent's world formed by reflecting on raw memories and experiences.
Memories in Hindsight are stored in banks (i.e. memory banks). When memories are added to Hindsight, they are pushed into either the world facts or experiences memory pathway. They are then represented as a combination of entities, relationships, and time series with sparse/dense vector representations to aid in later recall.
Hindsight provides three simple methods to interact with the system:
- **Retain:** Provide information to Hindsight that you want it to remember
- **Recall:** Retrieve memories from Hindsight
- **Reflect:** Reflect on memories and experiences to generate new observations and insights from existing memories.
### Retain
The `retain` operation is used to push new memories into Hindsight. It tells Hindsight to _retain_ the information you pass in as an input.
```python
from hindsight_client import Hindsight
client = Hindsight(base_url="http://localhost:8888")
# Simple
client.retain(
bank_id="my-bank",
content="Alice works at Google as a software engineer"
)
# With context and timestamp
client.retain(
bank_id="my-bank",
content="Alice got promoted to senior engineer",
context="career update",
timestamp="2025-06-15T10:00:00Z"
)
``` ```
Behind the scenes, the retain operation uses an LLM to extract key facts, temporal data, entities, and relationships. It passes these through a normalization process to transform extracted data into canonical entities, time series, and search indexes along with metadata. These representations create the pathways for accurate memory retrieval in the recall and reflect operations. ## What we changed
![Retain Operation](hindsight-docs/static/img/retain-operation.webp) A taxonomy layer over Hindsight's vector store, plus a standalone MCP server.
### Recall Key additions:
- `room_hall_classifier.py` — keyword-based taxonomy engine (new)
- `aa1_add_room_hall_to_memory_units.py` — DB migration: flat → hierarchical, adds room/hall + `layer` column (new)
- `mcp-server/` — standalone MCP server with 5 tools (new)
- Storage layer — room/hall/layer metadata on every write
- Retrieval — room-scoped search with hall filtering
- Compression — closet generation with source linking
- Tunnels — cross-bank memory sharing protocol
The recall operation is used to retrieve memories. These memories can come from any of the memory types (world, experiences, etc.) Full architectural spec: [RCLL.md](./RCLL.md)
```python ## Upstream compatibility
from hindsight_client import Hindsight
client = Hindsight(base_url="http://localhost:8888") This fork tracks `vectorize-io/hindsight` as upstream. To pull updates:
# Simple ```bash
client.recall(bank_id="my-bank", query="What does Alice do?") git remote add upstream https://github.com/vectorize-io/hindsight.git
git fetch upstream
# Temporal git merge upstream/main
client.recall(bank_id="my-bank", query="What happened in June?")
``` ```
Recall performs 4 retrieval strategies in parallel: All changes are additive — existing Hindsight behavior is preserved.
- Semantic: Vector similarity
- Keyword: BM25 exact matching
- Graph: Entity/temporal/causal links
- Temporal: Time range filtering
![Retain Operation](hindsight-docs/static/img/recall-operation.webp) ## Credits
The individual results from the retrievals are merged, then ordered by relevance using reciprocal rank fusion and a cross-encoder reranking model. - [**Hindsight**](https://github.com/vectorize-io/hindsight) by vectorize-io — the memory storage engine
- [Holetron](https://github.com/holetron-lab) — fork maintainers, MCP server, integration
The final output is trimmed as needed to fit within the token limit.
### Reflect
The reflect operation is used to perform a more thorough analysis of existing memories. This allows the agent to form new connections between memories and build a more thorough understanding of its world.
For example, the `reflect` operation can be used to support use cases such as:
- An **AI Project Manager** reflecting on what risks need to be mitigated on a project.
- A **Sales Agent** reflecting on why certain outreach messages have gotten responses while others haven't.
- A **Support Agent** reflecting on opportunities where customers have questions not answered by current product documentation.
The `reflect` operation can also be used to handle on-demand question answering or analysis which require more deep thinking.
```python
from hindsight_client import Hindsight
client = Hindsight(base_url="http://localhost:8888")
client.reflect(bank_id="my-bank", query="What should I know about Alice?")
```
![Retain Operation](hindsight-docs/static/img/reflect-operation.webp)
---
## Resources
**Documentation:**
- [https://hindsight.vectorize.io](https://hindsight.vectorize.io)
**Clients:**
- [Python](http://hindsight.vectorize.io/sdks/python)
- [Node.js](http://hindsight.vectorize.io/sdks/nodejs)
- [REST API](https://hindsight.vectorize.io/api-reference)
- [CLI](https://hindsight.vectorize.io/sdks/cli)
**Community:**
- [Slack](https://join.slack.com/t/hindsight-space/shared_invite/zt-3nhbm4w29-LeSJ5Ixi6j8PdiYOCPlOgg)
- [GitHub Issues](https://github.com/vectorize-io/hindsight/issues)
---
## Star History
[![Star History Chart](https://api.star-history.com/svg?repos=vectorize-io/hindsight&type=date&legend=top-left)](https://www.star-history.com/#vectorize-io/hindsight&type=date&legend=top-left)
---
## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md).
## License ## License
MIT — see [LICENSE](./LICENSE) MIT — same as upstream Hindsight. See [LICENSE](./LICENSE).
---
Built by [Vectorize.io](https://vectorize.io)
<img src="https://umami-pixel.chris-latimer.workers.dev/?id=a8b043e6-6964-454d-80df-69b69d3f0d50&host=github.com&url=/vectorize-io/hindsight" width="1" height="1" alt="" />