docs+skills: add main UI/UX visual-truth PRD and skill links
This commit is contained in:
ZenchantLive
parent
1c36223e7f
commit
14a50ad4ae
289 changed files with 54463 additions and 0 deletions
622
.agents/skills/rlm-mem/references/API.md
Normal file
622
.agents/skills/rlm-mem/references/API.md
Normal file
|
|
@ -0,0 +1,622 @@
|
|||
# RLM-MEM API Reference
|
||||
|
||||
## Core Classes
|
||||
|
||||
### ChunkStore
|
||||
|
||||
Main storage interface for memory chunks.
|
||||
|
||||
```python
|
||||
from brain.scripts import ChunkStore
|
||||
|
||||
store = ChunkStore("brain/memory")
|
||||
```
|
||||
|
||||
#### Methods
|
||||
|
||||
**create_chunk**
|
||||
```python
|
||||
def create_chunk(
|
||||
self,
|
||||
content: str,
|
||||
chunk_type: str = "note",
|
||||
metadata: dict = None,
|
||||
links: list = None,
|
||||
tags: list = None
|
||||
) -> Chunk:
|
||||
"""Create and store a new chunk.
|
||||
|
||||
Args:
|
||||
content: The text content to store
|
||||
chunk_type: Type of chunk (preference, fact, pattern, decision, note)
|
||||
metadata: Optional metadata dict
|
||||
links: Optional list of link dicts
|
||||
tags: Optional list of tag strings
|
||||
|
||||
Returns:
|
||||
Chunk dataclass instance
|
||||
"""
|
||||
```
|
||||
|
||||
**get_chunk**
|
||||
```python
|
||||
def get_chunk(self, chunk_id: str) -> Optional[Chunk]:
|
||||
"""Retrieve a chunk by ID.
|
||||
|
||||
Args:
|
||||
chunk_id: The chunk identifier
|
||||
|
||||
Returns:
|
||||
Chunk or None if not found
|
||||
"""
|
||||
```
|
||||
|
||||
**update_chunk**
|
||||
```python
|
||||
def update_chunk(
|
||||
self,
|
||||
chunk_id: str,
|
||||
content: str = None,
|
||||
metadata: dict = None,
|
||||
links: list = None,
|
||||
tags: list = None
|
||||
) -> Optional[Chunk]:
|
||||
"""Update an existing chunk.
|
||||
|
||||
Args:
|
||||
chunk_id: Chunk to update
|
||||
content: New content (optional)
|
||||
metadata: New metadata (optional)
|
||||
links: New links (optional)
|
||||
tags: New tags (optional)
|
||||
|
||||
Returns:
|
||||
Updated Chunk or None if not found
|
||||
"""
|
||||
```
|
||||
|
||||
**delete_chunk**
|
||||
```python
|
||||
def delete_chunk(
|
||||
self,
|
||||
chunk_id: str,
|
||||
permanent: bool = False
|
||||
) -> bool:
|
||||
"""Delete a chunk.
|
||||
|
||||
Args:
|
||||
chunk_id: Chunk to delete
|
||||
permanent: If True, permanently delete; else soft delete
|
||||
|
||||
Returns:
|
||||
True if deleted, False if not found
|
||||
"""
|
||||
```
|
||||
|
||||
**list_chunks**
|
||||
```python
|
||||
def list_chunks(
|
||||
self,
|
||||
conversation_id: str = None,
|
||||
start_date: str = None,
|
||||
end_date: str = None,
|
||||
tags: List[str] = None,
|
||||
chunk_type: str = None
|
||||
) -> List[str]:
|
||||
"""List chunk IDs matching filters.
|
||||
|
||||
Args:
|
||||
conversation_id: Filter by conversation
|
||||
start_date: Filter by date (YYYY-MM-DD)
|
||||
end_date: Filter by date (YYYY-MM-DD)
|
||||
tags: Filter by tags (ALL must match)
|
||||
chunk_type: Filter by chunk type
|
||||
|
||||
Returns:
|
||||
List of chunk IDs
|
||||
"""
|
||||
```
|
||||
|
||||
**get_stats**
|
||||
```python
|
||||
def get_stats(self) -> dict:
|
||||
"""Get storage statistics.
|
||||
|
||||
Returns:
|
||||
Dict with chunk_count, total_tokens, storage_size_mb
|
||||
"""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### RememberOperation
|
||||
|
||||
High-level interface for creating memories.
|
||||
|
||||
```python
|
||||
from brain.scripts import RememberOperation, ChunkStore
|
||||
|
||||
store = ChunkStore("brain/memory")
|
||||
remember = RememberOperation(store)
|
||||
```
|
||||
|
||||
#### Methods
|
||||
|
||||
**remember**
|
||||
```python
|
||||
def remember(
|
||||
self,
|
||||
content: str,
|
||||
conversation_id: str,
|
||||
tags: list = None,
|
||||
confidence: float = 0.7,
|
||||
chunk_type: str = None
|
||||
) -> dict:
|
||||
"""Store content as memory with automatic chunking and linking.
|
||||
|
||||
Args:
|
||||
content: Text content to remember
|
||||
conversation_id: Conversation context ID
|
||||
tags: Optional tags for categorization
|
||||
confidence: Confidence level (0.0-1.0)
|
||||
chunk_type: Optional type hint
|
||||
|
||||
Returns:
|
||||
{
|
||||
"success": bool,
|
||||
"chunk_ids": [str],
|
||||
"total_tokens": int,
|
||||
"chunks_created": int,
|
||||
"error": str (if failed)
|
||||
}
|
||||
"""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### REPLSession
|
||||
|
||||
Secure sandbox for recursive LLM execution.
|
||||
|
||||
```python
|
||||
from brain.scripts import REPLSession
|
||||
|
||||
repl = REPLSession(
|
||||
chunk_store=store,
|
||||
llm_client=llm_client,
|
||||
max_iterations=10,
|
||||
timeout_seconds=60,
|
||||
max_depth=5
|
||||
)
|
||||
```
|
||||
|
||||
#### Constructor Args
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| chunk_store | ChunkStore | required | Memory storage instance |
|
||||
| llm_client | object | required | LLM client with `complete()` method |
|
||||
| max_iterations | int | 10 | Max recursive calls |
|
||||
| timeout_seconds | int | 60 | Execution timeout |
|
||||
| max_depth | int | 5 | Max recursion depth |
|
||||
|
||||
#### Methods
|
||||
|
||||
**execute**
|
||||
```python
|
||||
def execute(self, code: str, timeout: int = None) -> Any:
|
||||
"""Execute Python code in sandbox.
|
||||
|
||||
Args:
|
||||
code: Python code to execute
|
||||
timeout: Optional timeout override
|
||||
|
||||
Returns:
|
||||
Result of last expression or None
|
||||
|
||||
Raises:
|
||||
SandboxViolation: If code violates security
|
||||
RuntimeError: If called after FINAL()
|
||||
TimeoutError: If execution times out
|
||||
"""
|
||||
```
|
||||
|
||||
**retrieve** (requires query parameter)
|
||||
```python
|
||||
def retrieve(
|
||||
self,
|
||||
query: str = None,
|
||||
max_iterations: int = None
|
||||
) -> Any:
|
||||
"""Execute retrieval workflow.
|
||||
|
||||
Args:
|
||||
query: The query to process
|
||||
max_iterations: Override default max iterations
|
||||
|
||||
Returns:
|
||||
Final answer from LLM or None if max iterations reached
|
||||
"""
|
||||
```
|
||||
|
||||
**llm_query**
|
||||
```python
|
||||
def llm_query(self, prompt: str, context: dict = None) -> str:
|
||||
"""Make recursive LLM call.
|
||||
|
||||
Args:
|
||||
prompt: Prompt to send to LLM
|
||||
context: Optional context dictionary
|
||||
|
||||
Returns:
|
||||
LLM response string
|
||||
|
||||
Raises:
|
||||
MaxIterationsError: If max iterations exceeded
|
||||
"""
|
||||
```
|
||||
|
||||
**get_state**
|
||||
```python
|
||||
def get_state(self) -> dict:
|
||||
"""Get current sandbox namespace state."""
|
||||
```
|
||||
|
||||
**get_result**
|
||||
```python
|
||||
def get_result(self) -> Any:
|
||||
"""Get result if FINAL() was called."""
|
||||
```
|
||||
|
||||
**is_complete**
|
||||
```python
|
||||
def is_complete(self) -> bool:
|
||||
"""Check if FINAL() has been called."""
|
||||
```
|
||||
|
||||
**reset**
|
||||
```python
|
||||
def reset(self):
|
||||
"""Clear all state and start fresh."""
|
||||
```
|
||||
|
||||
#### Context Manager
|
||||
|
||||
```python
|
||||
with REPLSession(store, llm_client) as repl:
|
||||
result = repl.execute("x = 42")
|
||||
# Auto-reset on exit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ChunkingEngine
|
||||
|
||||
Text chunking and content type detection.
|
||||
|
||||
```python
|
||||
from brain.scripts import ChunkingEngine
|
||||
|
||||
engine = ChunkingEngine(min_tokens=100, max_tokens=800)
|
||||
```
|
||||
|
||||
#### Constructor Args
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| min_tokens | int | 100 | Minimum tokens per chunk |
|
||||
| max_tokens | int | 800 | Maximum tokens per chunk |
|
||||
|
||||
#### Methods
|
||||
|
||||
**chunk**
|
||||
```python
|
||||
def chunk(
|
||||
self,
|
||||
content: str,
|
||||
conversation_id: str,
|
||||
tags: list = None
|
||||
) -> List[ChunkResult]:
|
||||
"""Split content into chunks.
|
||||
|
||||
Args:
|
||||
content: Text to chunk
|
||||
conversation_id: Conversation context
|
||||
tags: Optional tags
|
||||
|
||||
Returns:
|
||||
List of ChunkResult objects
|
||||
"""
|
||||
```
|
||||
|
||||
**detect_content_type**
|
||||
```python
|
||||
def detect_content_type(self, content: str) -> str:
|
||||
"""Detect content type from text.
|
||||
|
||||
Returns:
|
||||
One of: decision, pattern, preference, fact, note
|
||||
"""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### AutoLinker
|
||||
|
||||
Automatic and manual link management.
|
||||
|
||||
```python
|
||||
from brain.scripts import AutoLinker
|
||||
|
||||
linker = AutoLinker(chunk_store)
|
||||
```
|
||||
|
||||
#### Methods
|
||||
|
||||
**link_on_create**
|
||||
```python
|
||||
def link_on_create(self, chunk: Chunk) -> Chunk:
|
||||
"""Add automatic links to new chunk.
|
||||
|
||||
Creates:
|
||||
- context_of links (same conversation)
|
||||
- follows links (temporal proximity)
|
||||
- related_to links (shared tags)
|
||||
"""
|
||||
```
|
||||
|
||||
**add_manual_link**
|
||||
```python
|
||||
def add_manual_link(
|
||||
self,
|
||||
source_id: str,
|
||||
target_id: str,
|
||||
link_type: str,
|
||||
strength: float = 0.5,
|
||||
reasoning: str = None
|
||||
) -> bool:
|
||||
"""Add manual link between chunks.
|
||||
|
||||
Args:
|
||||
source_id: Source chunk ID
|
||||
target_id: Target chunk ID
|
||||
link_type: supports, contradicts, or custom
|
||||
strength: Link strength (0.0-1.0)
|
||||
reasoning: Optional explanation
|
||||
|
||||
Returns:
|
||||
True if successful
|
||||
"""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Classes
|
||||
|
||||
### Chunk
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class Chunk:
|
||||
id: str # Unique identifier
|
||||
content: str # Text content
|
||||
tokens: int # Token count
|
||||
type: str # Chunk type
|
||||
metadata: ChunkMetadata # Timestamps, confidence, etc.
|
||||
links: List[ChunkLinks] # Relationships
|
||||
tags: List[str] # Categories
|
||||
```
|
||||
|
||||
### ChunkMetadata
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class ChunkMetadata:
|
||||
created_at: str # ISO timestamp
|
||||
modified_at: str # ISO timestamp
|
||||
accessed_at: str # ISO timestamp
|
||||
access_count: int # Number of reads
|
||||
confidence: float # 0.0-1.0
|
||||
conversation_id: str # Context ID
|
||||
```
|
||||
|
||||
### ChunkLinks
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class ChunkLinks:
|
||||
target_id: str # Linked chunk ID
|
||||
type: str # Link type
|
||||
strength: float # 0.0-1.0
|
||||
created_at: str # ISO timestamp
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## REPL Functions
|
||||
|
||||
Functions available inside REPLSession sandbox:
|
||||
|
||||
### read_chunk
|
||||
```python
|
||||
def read_chunk(chunk_id: str) -> Optional[dict]:
|
||||
"""Read a chunk by ID.
|
||||
|
||||
Returns chunk as dict or None if not found.
|
||||
"""
|
||||
```
|
||||
|
||||
### search_chunks
|
||||
```python
|
||||
def search_chunks(query: str, limit: int = 10) -> List[str]:
|
||||
"""Search for chunks matching query.
|
||||
|
||||
Simple keyword search, returns list of chunk IDs.
|
||||
"""
|
||||
```
|
||||
|
||||
### list_chunks_by_tag
|
||||
```python
|
||||
def list_chunks_by_tag(tag: Union[str, List[str]]) -> List[str]:
|
||||
"""List chunks with given tag(s).
|
||||
|
||||
Args:
|
||||
tag: Single tag string or list of tags
|
||||
|
||||
Returns:
|
||||
List of chunk IDs
|
||||
"""
|
||||
```
|
||||
|
||||
### get_linked_chunks
|
||||
```python
|
||||
def get_linked_chunks(
|
||||
chunk_id: str,
|
||||
link_type: str = None
|
||||
) -> List[dict]:
|
||||
"""Get chunks linked to given chunk.
|
||||
|
||||
Args:
|
||||
chunk_id: Source chunk
|
||||
link_type: Optional filter by link type
|
||||
|
||||
Returns:
|
||||
List of linked chunk dicts with _link_type and _link_strength
|
||||
"""
|
||||
```
|
||||
|
||||
### llm_query
|
||||
```python
|
||||
def llm_query(prompt: str, context: dict = None) -> str:
|
||||
"""Make recursive LLM call.
|
||||
|
||||
Increments iteration count. Raises MaxIterationsError if exceeded.
|
||||
"""
|
||||
```
|
||||
|
||||
### FINAL
|
||||
```python
|
||||
def FINAL(answer: Any) -> None:
|
||||
"""Signal final answer and stop execution.
|
||||
|
||||
Can only be called once per session.
|
||||
"""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exceptions
|
||||
|
||||
### SandboxViolation
|
||||
```python
|
||||
class SandboxViolation(Exception):
|
||||
"""Raised when code attempts sandbox escape."""
|
||||
```
|
||||
|
||||
### MaxIterationsError
|
||||
```python
|
||||
class MaxIterationsError(Exception):
|
||||
"""Raised when max iterations exceeded."""
|
||||
```
|
||||
|
||||
### TimeoutError
|
||||
```python
|
||||
class TimeoutError(Exception):
|
||||
"""Raised when execution times out."""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Utility Functions
|
||||
|
||||
### init_storage
|
||||
```python
|
||||
from brain.scripts import init_storage
|
||||
|
||||
def init_storage(base_path: str) -> ChunkStore:
|
||||
"""Initialize storage directory structure.
|
||||
|
||||
Args:
|
||||
base_path: Root directory for storage
|
||||
|
||||
Returns:
|
||||
Configured ChunkStore instance
|
||||
"""
|
||||
```
|
||||
|
||||
### add_manual_link (module level)
|
||||
```python
|
||||
from brain.scripts import add_manual_link
|
||||
|
||||
def add_manual_link(
|
||||
chunk_store: ChunkStore,
|
||||
source_id: str,
|
||||
target_id: str,
|
||||
link_type: str,
|
||||
strength: float = 0.5,
|
||||
reasoning: str = None
|
||||
) -> bool:
|
||||
"""Convenience function for adding manual links."""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration Files
|
||||
|
||||
### Personalities
|
||||
|
||||
Read personality configurations:
|
||||
|
||||
```python
|
||||
def load_personality(mode: str) -> dict:
|
||||
"""Load personality from Markdown file."""
|
||||
# Reads: brain/personalities/{mode}.md
|
||||
# Parses slider values
|
||||
# Returns configuration dict
|
||||
```
|
||||
|
||||
### Sliders
|
||||
|
||||
Read slider specifications:
|
||||
|
||||
```python
|
||||
def load_slider(dimension: str) -> dict:
|
||||
"""Load slider from Markdown file."""
|
||||
# Reads: brain/sliders/{dimension}.md
|
||||
# Returns range, description, examples
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Constants
|
||||
|
||||
### Chunk Types
|
||||
```python
|
||||
CHUNK_TYPES = [
|
||||
"preference", # User preferences
|
||||
"fact", # Factual information
|
||||
"pattern", # Recognized patterns
|
||||
"decision", # Architectural decisions
|
||||
"note" # General notes
|
||||
]
|
||||
```
|
||||
|
||||
### Link Types
|
||||
```python
|
||||
AUTO_LINK_TYPES = [
|
||||
"context_of", # Same conversation
|
||||
"follows", # Temporal proximity
|
||||
"related_to" # Shared tags
|
||||
]
|
||||
|
||||
MANUAL_LINK_TYPES = [
|
||||
"supports", # Evidence supports
|
||||
"contradicts" # Evidence contradicts
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**See Also:**
|
||||
- [ARCHITECTURE.md](ARCHITECTURE.md) for system design
|
||||
- Main SKILL.md for usage examples
|
||||
376
.agents/skills/rlm-mem/references/ARCHITECTURE.md
Normal file
376
.agents/skills/rlm-mem/references/ARCHITECTURE.md
Normal file
|
|
@ -0,0 +1,376 @@
|
|||
# RLM-MEM Architecture
|
||||
|
||||
## System Overview
|
||||
|
||||
RLM-MEM Enhanced consists of two integrated subsystems:
|
||||
|
||||
1. **RLM Memory System** (New) - JSON-based persistent storage with graph linking
|
||||
2. **RLM-MEM Framework** (Original) - Markdown-based configuration for personalities and behavior
|
||||
|
||||
## Architecture Diagram
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ AGENT INTERFACE │
|
||||
│ (Natural language, API calls, or skill integration) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ RLM-MEM BRAIN LAYER │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ PERSONALITY │ │ MEMORY │ │ CONFIGURATION│ │
|
||||
│ │ SYSTEM │◄──►│ SYSTEM │◄──►│ SYSTEM │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
│ │ │ │ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────┐ │
|
||||
│ │ STORAGE LAYER │ │
|
||||
│ │ ┌──────────────┐ ┌──────────────────────┐ │ │
|
||||
│ │ │ Markdown │ │ JSON │ │ │
|
||||
│ │ │ Files │ │ (Memory Chunks) │ │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ │personalities/│ │ brain/memory/ │ │ │
|
||||
│ │ │sliders/ │ │ ├── YYYY-MM-DD/ │ │ │
|
||||
│ │ │gauges/ │ │ │ └── chunks │ │ │
|
||||
│ │ └──────────────┘ │ └── index.json │ │ │
|
||||
│ │ └──────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Component Deep Dive
|
||||
|
||||
### 1. Memory System Components
|
||||
|
||||
#### ChunkStore (`brain/scripts/memory_store.py`)
|
||||
- **Purpose**: CRUD operations for memory chunks
|
||||
- **Storage**: JSON files in date-organized directories
|
||||
- **Key Methods**:
|
||||
- `create_chunk()` - Store new chunk with auto-generated ID
|
||||
- `get_chunk()` - Retrieve chunk by ID with access tracking
|
||||
- `update_chunk()` - Modify existing chunk
|
||||
- `delete_chunk()` - Soft or permanent delete
|
||||
- `list_chunks()` - Query with filters (tags, date, conversation)
|
||||
|
||||
#### ChunkingEngine (`brain/scripts/chunking_engine.py`)
|
||||
- **Purpose**: Split text into semantically meaningful chunks
|
||||
- **Algorithm**: Simple bounded chunking (100-800 tokens)
|
||||
- **Process**:
|
||||
1. Split on paragraphs (`\n\n`)
|
||||
2. Merge small paragraphs (<100 tokens)
|
||||
3. Split large paragraphs (>800 tokens) at sentence boundaries
|
||||
4. Detect content type (decision, pattern, preference, fact, note)
|
||||
|
||||
#### AutoLinker (`brain/scripts/auto_linker.py`)
|
||||
- **Purpose**: Automatically create relationships between chunks
|
||||
- **Link Types**:
|
||||
- `context_of` - Same conversation context
|
||||
- `follows` - Temporal proximity (within 5 minutes)
|
||||
- `related_to` - Shared tags
|
||||
- `supports` - Manual: chunk supports another
|
||||
- `contradicts` - Manual: chunk contradicts another
|
||||
|
||||
#### REPLSession (`brain/scripts/repl_environment.py`)
|
||||
- **Purpose**: Secure sandbox for recursive LLM execution
|
||||
- **Security**:
|
||||
- AST-based code validation
|
||||
- Blocked imports (os, sys, subprocess, etc.)
|
||||
- Blocked builtins (eval, exec, compile, open)
|
||||
- Attribute access restrictions (__class__, __bases__, etc.)
|
||||
- Memory limits (10MB for string operations)
|
||||
- Timeout protection
|
||||
|
||||
### 2. Original RLM-MEM Framework Components
|
||||
|
||||
#### Personalities (`brain/personalities/*.md`)
|
||||
- **Purpose**: Pre-defined behavioral configurations
|
||||
- **Structure**:
|
||||
```markdown
|
||||
# [MODE] Mode
|
||||
|
||||
## Configuration
|
||||
- Creativity: [0-100]
|
||||
- Technicality: [0-100]
|
||||
- ...
|
||||
|
||||
## Description
|
||||
[When to use, characteristics]
|
||||
```
|
||||
- **Files**: BASE.md, RESEARCH_ANALYST.md, CREATIVE_DIRECTOR.md, TECHNICAL_COPILOT.md
|
||||
|
||||
#### Sliders (`brain/sliders/*.md`)
|
||||
- **Purpose**: Individual behavioral dimension controls
|
||||
- **Dimensions**: Creativity, Technicality, Humor, Directness, Morality, Soul, Identity, Tools, User
|
||||
- **Structure**:
|
||||
```markdown
|
||||
# [DIMENSION] Slider
|
||||
|
||||
## Range
|
||||
0-100
|
||||
|
||||
## Description
|
||||
[What this dimension controls]
|
||||
|
||||
## Examples
|
||||
- 0: [Minimal expression]
|
||||
- 50: [Moderate expression]
|
||||
- 100: [Maximal expression]
|
||||
```
|
||||
|
||||
#### Gauges (`brain/gauges/LIVEHUD.md`)
|
||||
- **Purpose**: Real-time system monitoring displays
|
||||
- **Function**: Visual feedback on system status
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Memory Creation Flow
|
||||
|
||||
```
|
||||
User Input
|
||||
│
|
||||
▼
|
||||
RememberOperation.remember()
|
||||
│
|
||||
├──► ChunkingEngine.chunk()
|
||||
│ │
|
||||
│ ├──► Split into paragraphs
|
||||
│ ├──► Merge small chunks
|
||||
│ ├──► Split large chunks
|
||||
│ └──► Detect content type
|
||||
│
|
||||
├──► ChunkStore.create_chunk()
|
||||
│ │
|
||||
│ ├──► Write JSON to disk
|
||||
│ └──► Update indexes
|
||||
│
|
||||
└──► AutoLinker.link_on_create()
|
||||
│
|
||||
├──► Add context_of links
|
||||
├──► Add follows links
|
||||
└──► Add related_to links
|
||||
```
|
||||
|
||||
### Memory Retrieval Flow
|
||||
|
||||
```
|
||||
User Query
|
||||
│
|
||||
▼
|
||||
REPLSession.retrieve(query)
|
||||
│
|
||||
├──► Build retrieval prompt
|
||||
│
|
||||
├──► LLM generates search code
|
||||
│ │
|
||||
│ └──► "candidates = search_chunks('query')"
|
||||
│
|
||||
├──► Execute code in sandbox
|
||||
│ │
|
||||
│ ├──► search_chunks() → ChunkStore.list_chunks()
|
||||
│ ├──► read_chunk() → ChunkStore.get_chunk()
|
||||
│ └──► FINAL(answer)
|
||||
│
|
||||
└──► Return final answer
|
||||
```
|
||||
|
||||
## Storage Schema
|
||||
|
||||
### Memory Chunk Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "chunk-YYYY-MM-DD-UUID",
|
||||
"content": "String content",
|
||||
"tokens": 42,
|
||||
"type": "preference|fact|pattern|decision|note",
|
||||
"metadata": {
|
||||
"created_at": "ISO-8601 timestamp",
|
||||
"modified_at": "ISO-8601 timestamp",
|
||||
"accessed_at": "ISO-8601 timestamp",
|
||||
"access_count": 0,
|
||||
"confidence": 0.95
|
||||
},
|
||||
"links": [
|
||||
{
|
||||
"target_id": "chunk-id",
|
||||
"type": "context_of|follows|related_to|supports|contradicts",
|
||||
"strength": 0.8,
|
||||
"created_at": "timestamp"
|
||||
}
|
||||
],
|
||||
"tags": ["tag1", "tag2"]
|
||||
}
|
||||
```
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
brain/memory/
|
||||
├── SCHEMA.md # Documentation
|
||||
├── 2026-02-10/ # Date-organized storage
|
||||
│ ├── chunk-001.json
|
||||
│ └── index.json # Daily manifest
|
||||
├── tags/ # Tag indexes
|
||||
│ └── {tag}.json # Chunks by tag
|
||||
└── links/ # Link graph indexes
|
||||
└── graph.json # Full link graph
|
||||
```
|
||||
|
||||
## Security Model
|
||||
|
||||
### Sandbox Security Layers
|
||||
|
||||
1. **AST Validation** (Static)
|
||||
- Parse code into AST
|
||||
- Check for blocked imports
|
||||
- Check for dangerous builtins
|
||||
- Check for attribute exploitation
|
||||
|
||||
2. **Restricted Namespace** (Runtime)
|
||||
- Limited builtins dictionary
|
||||
- No direct file system access
|
||||
- Mocked sys module (stderr only)
|
||||
- Wrapped memory functions
|
||||
|
||||
3. **Resource Limits**
|
||||
- Memory: 10MB string limit
|
||||
- Time: Configurable timeout (default 60s)
|
||||
- Iterations: Configurable max (default 10)
|
||||
|
||||
### Blocked Operations
|
||||
|
||||
```python
|
||||
# Imports
|
||||
os, sys, subprocess, socket, urllib, http, ftplib, smtplib, etc.
|
||||
|
||||
# Builtins
|
||||
eval, exec, compile, open, __import__
|
||||
|
||||
# Attributes
|
||||
__class__, __bases__, __subclasses__, __globals__, __code__, etc.
|
||||
|
||||
# Operations
|
||||
# - File system access outside brain/memory/
|
||||
# - Network operations
|
||||
# - Process creation
|
||||
# - Code object manipulation
|
||||
```
|
||||
|
||||
## Performance Characteristics
|
||||
|
||||
### Time Complexity
|
||||
|
||||
| Operation | Complexity | Notes |
|
||||
|-----------|-----------|-------|
|
||||
| Create chunk | O(1) | File write + index update |
|
||||
| Get chunk | O(1) | Direct file access |
|
||||
| List chunks | O(n) | Scans index files |
|
||||
| Search by tag | O(1) | Uses tag index |
|
||||
| Auto-link | O(n) | Scans recent chunks |
|
||||
| REPL execute | O(code) | Depends on code complexity |
|
||||
|
||||
### Storage Overhead
|
||||
|
||||
- Each chunk: ~500 bytes metadata + content
|
||||
- Index files: ~100 bytes per entry
|
||||
- Link graph: ~200 bytes per link
|
||||
- Recommended: <10,000 chunks per directory
|
||||
|
||||
## Extension Points
|
||||
|
||||
### Custom Chunk Types
|
||||
|
||||
Define new types in application code:
|
||||
|
||||
```python
|
||||
# custom_types.py
|
||||
CHUNK_TYPES = {
|
||||
'api_endpoint': {
|
||||
'description': 'API endpoint documentation',
|
||||
'required_fields': ['method', 'path'],
|
||||
'optional_fields': ['auth', 'params', 'response']
|
||||
},
|
||||
'database_schema': {
|
||||
'description': 'Database table/column info',
|
||||
'required_fields': ['table_name'],
|
||||
'optional_fields': ['columns', 'indexes', 'relationships']
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Link Types
|
||||
|
||||
Add relationship types:
|
||||
|
||||
```python
|
||||
# In auto_linker.py or application code
|
||||
CUSTOM_LINK_TYPES = {
|
||||
'implements': 'Chunk implements described functionality',
|
||||
'tests': 'Chunk contains tests for target',
|
||||
'depends_on': 'Chunk depends on target chunk'
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Personalities
|
||||
|
||||
Create new personality modes:
|
||||
|
||||
```markdown
|
||||
# brain/personalities/CUSTOM_MODE.md
|
||||
# [MODE] Mode
|
||||
|
||||
## Configuration
|
||||
- Creativity: 75
|
||||
- Technicality: 60
|
||||
- ...
|
||||
|
||||
## Description
|
||||
[When to use this mode]
|
||||
```
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### Pattern: Agent with Memory
|
||||
|
||||
```python
|
||||
class MemoryEnabledAgent:
|
||||
def __init__(self, personality="BASE"):
|
||||
self.memory = ChunkStore("brain/memory")
|
||||
self.remember = RememberOperation(self.memory)
|
||||
self.personality = self._load_personality(personality)
|
||||
|
||||
def process(self, user_input):
|
||||
# 1. Retrieve relevant context
|
||||
context = self._get_relevant_memories(user_input)
|
||||
|
||||
# 2. Generate response using personality
|
||||
response = self._generate(user_input, context)
|
||||
|
||||
# 3. Store exchange
|
||||
self._store_exchange(user_input, response)
|
||||
|
||||
return response
|
||||
```
|
||||
|
||||
### Pattern: Project-Specific Memory
|
||||
|
||||
```python
|
||||
class ProjectMemory:
|
||||
def __init__(self, project_name):
|
||||
self.store = ChunkStore(f"brain/memory/projects/{project_name}")
|
||||
self.project_name = project_name
|
||||
|
||||
def store_decision(self, decision, rationale):
|
||||
return self.store.create_chunk(
|
||||
content=f"Decision: {decision}\nRationale: {rationale}",
|
||||
type="decision",
|
||||
tags=["decision", self.project_name]
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Next**: See [API.md](API.md) for detailed API reference.
|
||||
Loading…
Add table
Add a link
Reference in a new issue