sandclaw-memory

from sandclaw_memory import BrainMemory
brain = BrainMemory(tag_extractor=my_ai_func)
brain.save("User loves Python and React")
context = brain.recall("what does the user like?")
# -> Returns relevant memories as Markdown, ready for LLM injection

Why sandclaw-memory?

The Self-Growing Advantage

Day 1: "Built a page with React" → AI extracts: [react, frontend, page]
 keyword_map registers: "React" → react, "page" → page
Day 30: "React Native app" → keyword_map instant match! No AI needed.
 Cost: 0ドル.00
Day 90: 80% of saves match keyword_map → AI calls reduced by 80%

Quick Start

Install

pip install sandclaw-memory

3-Line Memory

from sandclaw_memory import BrainMemory
with BrainMemory(tag_extractor=my_tag_func) as brain:
 brain.save("Important: migrate to FastAPI by Q2")
 print(brain.recall("what's the migration plan?"))

With OpenAI

import json, openai
from sandclaw_memory import BrainMemory
def tag_extractor(content: str) -> list[str]:
 resp = openai.chat.completions.create(
 model="gpt-4o-mini",
 messages=[{
 "role": "system",
 "content": "Extract 3-7 keyword tags. Return JSON array only."
 }, {"role": "user", "content": content}],
 temperature=0,
 )
 return json.loads(resp.choices[0].message.content)
with BrainMemory(
 db_path="./my_memory",
 tag_extractor=tag_extractor,
) as brain:
 brain.start_polling() # Background tag extraction every 15s
 brain.save("User prefers Python and TypeScript")
 brain.save("Decided to use PostgreSQL", source="archive")
 context = brain.recall("what tech stack?")
 # Inject 'context' into your LLM's system prompt

With Claude

import json, anthropic
from sandclaw_memory import BrainMemory
client = anthropic.Anthropic()
def tag_extractor(content: str) -> list[str]:
 resp = client.messages.create(
 model="claude-haiku-4-5-20251001",
 max_tokens=200,
 messages=[{"role": "user",
 "content": f"Extract 3-7 tags as JSON array:\n{content}"}],
 )
 return json.loads(resp.content[0].text)
brain = BrainMemory(tag_extractor=tag_extractor)

Architecture

┌─────────────────────────────────────────────────┐
│ BrainMemory │
│ save() → recall() → start_polling() │
├─────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌──────────┐ ┌────────────────┐ │
│ │ L1 │ │ L2 │ │ L3 │ │
│ │ Session │ │ Summary │ │ Archive │ │
│ │ │ │ │ │ │ │
│ │ 3-day │ │ 30-day │ │ Permanent │ │
│ │ rolling │ │ AI/text │ │ SQLite + FTS5 │ │
│ │ Markdown│ │ summary │ │ + self-growing │ │
│ │ logs │ │ │ │ tag dict │ │
│ └────┬────┘ └────┬─────┘ └───────┬────────┘ │
│ │ │ │ │
│ ┌────┴────────────┴────────────────┴────────┐ │
│ │ Intent Dispatcher │ │
│ │ CASUAL → L1 │ STANDARD → L1+L2 │ │
│ │ │ DEEP → L1+L2+L3 │ │
│ └───────────────┴───────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ Self-Growing Tag Pipeline │ │
│ │ Stage 1: keyword_map (instant, free) │ │
│ │ Stage 2: AI callback (async, queue) │ │
│ │ → keyword_map grows → Stage 2 shrinks │ │
│ └──────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘

Three Memory Layers

Intent-Based Depth

brain.recall("what time is it?") # → CASUAL (L1 only)
brain.recall("summarize this month") # → STANDARD (L1 + L2)
brain.recall("why did we pick React?") # → DEEP (L1 + L2 + L3)
# Or override manually:
brain.recall("anything", depth="deep")

API Reference

BrainMemory

BrainMemory(
 db_path="./memory", # Where to store files
 tag_extractor=my_func, # REQUIRED: (str) -> list[str]
 promote_checker=None, # Optional: (str) -> bool
 depth_detector=None, # Optional: (str) -> str
 duplicate_checker=None, # Optional: (str, str) -> bool
 conflict_resolver=None, # Optional: (str, str) -> str
 polling_interval=15, # Seconds between maintenance cycles
 rolling_days=3, # L1 retention period
 summary_days=30, # L2 summary period
 max_context_chars=15_000, # Context budget for LLM injection
 encryption_key=None, # Optional SQLCipher encryption
)

Core Methods

The 5 AI Callbacks

Event Hooks

brain.on("before_save", lambda content, source: ...)
brain.on("after_save", lambda content, source: ...)
brain.on("before_promote", lambda content: ...)
brain.on("after_promote", lambda content, mem_id: ...)
brain.on("after_recall", lambda query, depth, result: ...)
brain.on("after_cycle", lambda stats: ...)

Examples

Compatibility

Contributing

License

Origin