13 KiB
13 KiB
RLM-MEM API Reference
Core Classes
ChunkStore
Main storage interface for memory chunks.
from brain.scripts import ChunkStore
store = ChunkStore("brain/memory")
Methods
create_chunk
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
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
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
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
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
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.
from brain.scripts import RememberOperation, ChunkStore
store = ChunkStore("brain/memory")
remember = RememberOperation(store)
Methods
remember
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.
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
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)
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
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
def get_state(self) -> dict:
"""Get current sandbox namespace state."""
get_result
def get_result(self) -> Any:
"""Get result if FINAL() was called."""
is_complete
def is_complete(self) -> bool:
"""Check if FINAL() has been called."""
reset
def reset(self):
"""Clear all state and start fresh."""
Context Manager
with REPLSession(store, llm_client) as repl:
result = repl.execute("x = 42")
# Auto-reset on exit
ChunkingEngine
Text chunking and content type detection.
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
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
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.
from brain.scripts import AutoLinker
linker = AutoLinker(chunk_store)
Methods
link_on_create
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
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
@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
@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
@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
def read_chunk(chunk_id: str) -> Optional[dict]:
"""Read a chunk by ID.
Returns chunk as dict or None if not found.
"""
search_chunks
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
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
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
def llm_query(prompt: str, context: dict = None) -> str:
"""Make recursive LLM call.
Increments iteration count. Raises MaxIterationsError if exceeded.
"""
FINAL
def FINAL(answer: Any) -> None:
"""Signal final answer and stop execution.
Can only be called once per session.
"""
Exceptions
SandboxViolation
class SandboxViolation(Exception):
"""Raised when code attempts sandbox escape."""
MaxIterationsError
class MaxIterationsError(Exception):
"""Raised when max iterations exceeded."""
TimeoutError
class TimeoutError(Exception):
"""Raised when execution times out."""
Utility Functions
init_storage
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)
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:
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:
def load_slider(dimension: str) -> dict:
"""Load slider from Markdown file."""
# Reads: brain/sliders/{dimension}.md
# Returns range, description, examples
Constants
Chunk Types
CHUNK_TYPES = [
"preference", # User preferences
"fact", # Factual information
"pattern", # Recognized patterns
"decision", # Architectural decisions
"note" # General notes
]
Link Types
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 for system design
- Main SKILL.md for usage examples