Initial commit: RA-H Open Source Edition
Local-first knowledge management system with BYO API keys. Features: - 3-panel UI (Nodes | Focus | Helpers) - SQLite + sqlite-vec for vector search - Agent system (Easy/Hard mode orchestrators) - Content extraction (YouTube, PDF, web) - Integrate workflow for connection discovery - Dimension system with auto-assignment Tech stack: - Next.js 15 + TypeScript + Tailwind CSS - Anthropic (Claude) + OpenAI (GPT) via Vercel AI SDK Setup: npm install && npm rebuild better-sqlite3 scripts/dev/bootstrap-local.sh npm run dev MIT License
This commit is contained in:
“BeeRad”
@@ -0,0 +1,148 @@
|
||||
# Context & Memory
|
||||
|
||||
## Context Builder
|
||||
|
||||
The context builder assembles the information each agent sees during conversations. It creates **cacheable blocks** (for Anthropic) and structured context for all agents.
|
||||
|
||||
### Context Structure
|
||||
|
||||
Every agent receives:
|
||||
|
||||
**1. Base Context**
|
||||
- How nodes, edges, and dimensions work
|
||||
- Node reference format: `[NODE:id:"title"]`
|
||||
- If auto-context is enabled, BACKGROUND CONTEXT explains that the 10 most-connected nodes will be listed later
|
||||
- Pronouns like "this conversation/paper/video" refer to focused node
|
||||
|
||||
**2. Agent Instructions**
|
||||
- Agent-specific system prompt (ra-h, ra-h-easy, wise-rah, mini-rah)
|
||||
- Role-specific behavior guidelines
|
||||
- Execution approach and response style
|
||||
|
||||
**3. Tool Definitions**
|
||||
- Role-specific tools (orchestrator/executor/planner)
|
||||
- Each tool's description and parameters
|
||||
- Usage guidelines
|
||||
|
||||
**4. Workflow Definitions** (orchestrators only)
|
||||
- Available workflows (integrate, etc.)
|
||||
- Workflow descriptions and triggers
|
||||
- Only shown to ra-h and ra-h-easy
|
||||
|
||||
**5. Background Context (auto-context hubs)** (orchestrators only)
|
||||
- Optional block controlled by `~/Library/Application Support/RA-H/config/settings.json`
|
||||
- Lists the 10 nodes with the highest edge counts (ID + title + edge count)
|
||||
- Reminds agents to call `queryNodes`/`getNodesById` for full content
|
||||
- Ordered by edge count, then most recently updated to break ties
|
||||
|
||||
**6. Focused Nodes**
|
||||
- Primary focused node (active tab)
|
||||
- Additional focused nodes (other open tabs)
|
||||
- 25-word content previews
|
||||
- Chunk status and embedding availability
|
||||
- Link information
|
||||
|
||||
### Context Caching
|
||||
|
||||
**Anthropic (Claude):**
|
||||
- Explicit cache control blocks (`cache_control: {type: 'ephemeral'}`)
|
||||
- Caches base context, instructions, tools, workflows, background context
|
||||
- Focused nodes NOT cached (changes frequently)
|
||||
|
||||
**OpenAI (GPT):**
|
||||
- Implicit caching based on prefix matching
|
||||
- Same block structure for consistency
|
||||
- No explicit cache control markers needed
|
||||
|
||||
### Truncation Strategy
|
||||
|
||||
- **Background context:** IDs + titles only to keep the block lightweight
|
||||
- **Focused nodes:** 25-word previews
|
||||
- **Full content access:** Agents use `queryNodes`, `getNodesById`, `searchContentEmbeddings` for complete content
|
||||
- **Chunk status indicator:** Shows if embeddings are available (avoid re-extraction)
|
||||
|
||||
## Memory System (Legacy)
|
||||
|
||||
The automatic memory pipeline has been removed. Existing memory nodes remain in the database for archival purposes, but no new ones are created and they are excluded from auto-context. The old files (`src/services/memory/**`) have been deleted along with the `ENABLE_CHAT_MEMORY_PIPELINE` toggle. Future improvements should store long-term knowledge as normal nodes with explicit dimensions rather than a background pipeline.
|
||||
6. Update checkpoint in `chat_memory_state`
|
||||
|
||||
**Location:**
|
||||
- Pipeline: `/src/services/memory/synthesis/chatMemoryPipeline.ts`
|
||||
- Trigger: `/src/services/chat/middleware.ts:168-178`
|
||||
- Extraction: `/src/services/memory/synthesis/llmSynthesis.ts`
|
||||
|
||||
### Memory Node Structure
|
||||
|
||||
```typescript
|
||||
{
|
||||
type: 'memory',
|
||||
title: 'Insight on [subject]',
|
||||
description: 'Multi-line list of facts',
|
||||
content: 'Second-person statements combined',
|
||||
metadata: {
|
||||
category: 'identity' | 'interests' | 'models' | 'preferences' | 'relationships',
|
||||
subject_type: 'person' | 'project' | 'concept' | 'resource' | 'organization' | 'workflow',
|
||||
source_thread: string,
|
||||
source_helper: string,
|
||||
importance: 'low' | 'medium' | 'high',
|
||||
focused_node_titles: string[],
|
||||
canonical_key: string | null,
|
||||
subject: string
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Memory Categories
|
||||
|
||||
- **identity** - Who you are, your roles, background
|
||||
- **interests** - What you're curious about, learning, exploring
|
||||
- **models** - How you think, mental frameworks, approaches
|
||||
- **preferences** - What you like/dislike, priorities, values
|
||||
- **relationships** - Connections to people, projects, concepts
|
||||
|
||||
### Subject Types
|
||||
|
||||
Memory extraction classifies subjects into these types:
|
||||
|
||||
- **person** - Individual people (yourself or collaborators)
|
||||
- **project** - Projects, products, or initiatives
|
||||
- **concept** - Ideas, theories, mental models, beliefs
|
||||
- **resource** - Tools, articles, books, references
|
||||
- **organization** - Companies, institutions, communities
|
||||
- **workflow** - Processes, systems, methodologies
|
||||
|
||||
### Importance Levels
|
||||
|
||||
Each memory fact is classified by importance:
|
||||
|
||||
- **high** - Explicitly marked as priority, main project, strong belief ("is crucial", "must")
|
||||
- **medium** - Normal statements and observations (default)
|
||||
- **low** - Tentative, uncertain, or exploratory statements
|
||||
|
||||
## Auto-Context Toggle
|
||||
|
||||
Auto-context replaces manual pinning. When enabled, BACKGROUND CONTEXT includes the 10 nodes with the highest edge counts.
|
||||
|
||||
**How it works:**
|
||||
1. Settings UI exposes a toggle inside the Context tab.
|
||||
2. The toggle writes to `~/Library/Application Support/RA-H/config/settings.json`.
|
||||
3. Context builder and workflows read that file on each request (missing file defaults to `false`).
|
||||
4. When enabled, the following query runs once per request:
|
||||
|
||||
```sql
|
||||
SELECT n.id,
|
||||
n.title,
|
||||
COUNT(DISTINCT e.id) AS edge_count,
|
||||
n.updated_at
|
||||
FROM nodes n
|
||||
LEFT JOIN edges e ON (e.from_node_id = n.id OR e.to_node_id = n.id)
|
||||
WHERE n.type IS NULL OR n.type != 'memory'
|
||||
GROUP BY n.id
|
||||
ORDER BY edge_count DESC, n.updated_at DESC
|
||||
LIMIT 10;
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
- Only orchestrators (ra-h / ra-h-easy) see the block.
|
||||
- Titles + edge counts are shown; agents must call `queryNodes`/`getNodesById` for content.
|
||||
- Users who previously pinned nodes are auto-migrated to `autoContextEnabled: true` the first time the toggle helper runs and sees legacy pins.
|
||||
Reference in New Issue
Block a user