fleet-memory/RCLL.md

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:

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.

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.

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:

{
    "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:

{
    "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.