622 lines
13 KiB
Markdown
622 lines
13 KiB
Markdown
# 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
|