Skip to content

rdr-072-progressive-context-loading.md

Latest commit

 

History

History
114 lines (78 loc) · 5.04 KB

rdr-072-progressive-context-loading.md

File metadata and controls

114 lines (78 loc) · 5.04 KB
Raw
title RDR-072: Progressive Context Loading
status closed
close_reason implemented
close_date 2026-04-13
type feature
priority P2
created 2026-04-13
accepted_date 2026-04-13
reviewed-by self

RDR-072: Progressive Context Loading

Inspired by MemPalace's 4-layer memory stack (L0-L3). Reduce cold-start latency for agent sessions by assembling a project context packet at session start.

Problem

Every agent session starts cold. The agent has no project context until it runs a search query. For the first few interactions, the agent is working blind, often asking questions that the taxonomy, recent activity, or project identity could answer instantly.

MemPalace solves this with a ~600 token wake-up: identity (L0, ~100 tokens) + essential story (L1, ~500 tokens). The agent knows who it is and what matters before the first user message.

Nexus has the raw material (CLAUDE.md, taxonomy labels, recent memory, catalog stats) but no mechanism to assemble and inject it.

Research

RF-072-1: MemPalace layer architecture

Source: mempalace/layers.py

Layer Tokens Content When loaded
L0 ~100 Identity: name, traits, key people, current project Always (session start)
L1 ~500-800 Essential story: top moments from the palace, importance-ranked Always (session start)
L2 ~200-500 each On-demand: wing/room-specific context when topic comes up On mention
L3 Unlimited Deep search: full ChromaDB semantic search On query

Wake-up cost: ~600-900 tokens. Leaves 95%+ of context free.

RF-072-2: Available context sources in nexus

Source What it provides Tokens
CLAUDE.md Project structure, conventions, commands Already injected by Claude Code
nx taxonomy status output Topic labels with doc counts per collection ~50-200 tokens
Recent T2 memory entries Project decisions, notes, findings ~100-300 tokens
Catalog stats Document counts, link counts, content types ~50 tokens
Recent git activity What changed recently ~50-100 tokens

Total potential: ~300-650 tokens on top of CLAUDE.md.

RF-072-3: Injection mechanism

The SessionStart hook (conexus/hooks/scripts/session_start_hook.py) already runs at every session start and injects content into the system reminder. It currently injects:

  • Ready beads
  • nx capabilities summary
  • T1 scratch initialization

Adding a project context section is a natural extension. The content would be generated once and cached in T2 memory (refreshed when taxonomy or memory changes).

Design

Layer 0: Project identity (~100 tokens)

Extracted from CLAUDE.md (already injected) + catalog stats. No new work needed for L0. CLAUDE.md IS the identity layer.

Layer 1: Topic map (~200 tokens)

Generated from taxonomy: top 10-15 topic labels per collection, grouped by prefix (code/docs/knowledge/rdr). Cached in T2 memory as project_context_l1.

Example output:

Project knowledge map:
  code: GPU Kernel Programming (1294), Latency Benchmarking (1272), JUnit Testing (1202)
  knowledge: Organization Member Services (71), Byzantine Consensus (68), Bloom Filters (53)
  rdr: Bead Composition Probe (91), Content-addressed Resolution (75), Catalog Link Graph (62)

Layer 2: On-demand context (existing)

Already served by search() and query() MCP tools. No change needed. The topic parameter enables scoped retrieval: search(query="...", topic="Byzantine Consensus").

Layer 3: Deep search (existing)

Already served by /conexus:query skill for multi-step analytical queries. No change needed.

Refresh strategy

The L1 context is regenerated when:

  • nx taxonomy discover runs (topics changed)
  • nx index repo completes (corpus changed)
  • Explicitly via nx context refresh (new command)

Cached as per-repo flat files at ~/.config/nexus/context/<repo>-<hash>.txt (not T2, because opening T2Database takes 1.7s due to 4 SQLite connections + migrations). Global fallback at ~/.config/nexus/context_l1.txt (via --global). The hook reads the per-repo file in <1ms. Regenerated by nx taxonomy discover, nx index repo, and nx context refresh.

RF-072-4: Measured performance (2026-04-13)

  • Topic map from 92 collections, 2095 topics: 793 chars, ~198 tokens
  • SQLite query: 0.5ms (with LIMIT 20)
  • T2Database open: 1.7s (too slow for hook)
  • File read: <1ms (the right approach)

Success Criteria

  • SC-1: SessionStart hook injects topic map in < 200 tokens
  • SC-2: Agent can answer "what topics exist in this project?" without searching
  • SC-3: Context refreshes automatically after discover/index
  • SC-4: No measurable latency increase on session start (< 100ms for L1 generation from cache)

Open Questions

  1. Should L1 include recent memory entries (decisions, findings) or just taxonomy? (Proposed: taxonomy only for v1, memory in v2)
  2. Should the topic map be per-collection or aggregated? (Proposed: aggregated, grouped by prefix)
  3. How many topics per collection in L1? (Proposed: top 5 by doc_count, capped at 200 tokens total)