smart-memory

name	smart-memory
description	Context-aware memory for AI agents with dual retrieval modes — fast vector search or curated Focus Agent synthesis. SQLite backend, zero configuration, local embeddings.

Smart Memory v2.1 - Focus Agent Edition

Drop-in replacement for OpenClaw's memory system with superior search quality and optional curated retrieval via Focus Agent.

Features

• Hybrid Search: Combines FTS5 keyword search (BM25) with semantic vector search
• Focus Agent: Multi-pass curation for complex queries (retrieve → rank → synthesize)
• Dual Modes: Fast (direct) or Focus (curated) — toggle anytime
• SQLite Backend: Single-file database, no external services
• 100% Local: Embeddings run locally with Transformers.js (no API keys)
• Auto-Optimization: Uses sqlite-vec when available for native vector ops
• Zero Configuration: Works immediately after install

Installation

npx clawhub install smart-memory

Or from ClawHub: https://clawhub.ai/BluePointDigital/smart-memory

Quick Start

1. Sync Memory

node smart-memory/smart_memory.js --sync

2. Search (Fast Mode - Default)

node smart-memory/smart_memory.js --search "James values principles"

3. Enable Focus Mode (Curated Retrieval)

node smart-memory/smart_memory.js --focus
node smart-memory/smart_memory.js --search "complex decision about project direction"

4. Disable Focus Mode

node smart-memory/smart_memory.js --unfocus

Search Modes

Fast Mode (Default)

Direct vector similarity search. Best for:

• Simple lookups
• Quick fact retrieval
• Routine queries

node smart-memory/smart_memory.js --search "git remote"

Focus Mode (Curated)

Multi-pass curation via Focus Agent. Best for:

• Complex decisions
• Multi-fact synthesis
• Planning and strategy
• Comparing options

node smart-memory/smart_memory.js --focus
node smart-memory/smart_memory.js --search "What did we decide about BluePointDigital architecture?"

How Focus Mode Works:

1. Retrieve 20+ chunks (broad net)
2. Rank by weighted relevance (vector + term matching + source boost)
3. Synthesize into coherent narrative
4. Deliver structured context with confidence scores

How It Works

Hybrid Search Algorithm

1. FTS5 finds exact keyword matches (BM25 ranking)
2. Vector search finds semantic matches (cosine similarity)
3. Merged results using weighted scoring:
   • 70% vector score + 30% keyword score
   • Catches both "what you mean" and "exact tokens"

Focus Agent Curation

When enabled, searches go through additional processing:

Query: "What did we decide about BluePointDigital?"

┌─────────────────┐
│  Retrieve 20+   │  ← Vector similarity
│    chunks       │
└────────┬────────┘
         ▼
┌─────────────────┐
│   Weighted      │  ← Term matching
│    Ranking      │    Source boosting
│                 │    Recency boost
└────────┬────────┘
         ▼
┌─────────────────┐
│   Select Top 5  │  ← Threshold filtering
└────────┬────────┘
         ▼
┌─────────────────┐
│   Synthesize    │  ← Group by source
│   Narrative     │    Extract key facts
└────────┬────────┘
         ▼
    Structured output with confidence

Tools

memory_search

memory_search({
    query: "deployment configuration",
    maxResults: 5
})

Returns (Fast Mode):

{
    "query": "deployment configuration",
    "mode": "fast",
    "results": [
        {
            "path": "MEMORY.md",
            "from": 42,
            "lines": 8,
            "score": 0.89,
            "snippet": "..."
        }
    ]
}

Returns (Focus Mode):

{
    "query": "deployment configuration",
    "mode": "focus",
    "confidence": 0.87,
    "sources": ["MEMORY.md", "memory/2026-02-05.md"],
    "synthesis": "Relevant context for: \"deployment configuration\"\n\nFrom MEMORY.md:\n  • Docker setup uses docker-compose...\n  • Production deployment on AWS...\n\nFrom memory/2026-02-05.md:\n  • Decided to use Railway instead...",
    "facts": [
        {
            "content": "Docker setup uses docker-compose...",
            "source": "MEMORY.md",
            "lines": "42-50",
            "confidence": 0.89
        }
    ]
}

memory_get

memory_get({
    path: "MEMORY.md",
    from: 42,
    lines: 10
})

memory_mode (Focus Toggle)

memory_mode('focus')    // Enable curated retrieval
memory_mode('fast')     // Disable curated retrieval
memory_mode()           // Get current mode status

CLI Commands

# Sync memory files
node smart_memory.js --sync

# Search (uses current mode)
node smart_memory.js --search "query" [--max-results N]

# Search with mode override
node smart_memory.js --search "query" --focus
node smart_memory.js --search "query" --fast

# Toggle modes
node smart_memory.js --focus      # Enable focus mode
node smart_memory.js --unfocus    # Disable focus mode
node smart_memory.js --fast       # Same as --unfocus

# Check status
node smart_memory.js --status     # Database stats + current mode
node smart_memory.js --mode       # Current mode details

# Focus agent only
node focus_agent.js --search "query"
node focus_agent.js --suggest "query"  # Check if focus recommended

# Mode management
node memory_mode.js focus
node memory_mode.js unfocus
node memory_mode.js status

Performance

Feature	Fallback	With sqlite-vec
Keyword search	FTS5 (native)	FTS5 (native)
Vector search	JS cosine	Native KNN
Focus curation	+50-100ms	+50-100ms
Speed	~100 chunks/sec	~10,000 chunks/sec
Memory	All in RAM	DB handles it

When to Use Focus Mode

Use --focus or enable focus mode when:

• Query involves multiple related concepts
• You need synthesized context, not raw chunks
• Making decisions that require understanding relationships
• Summarizing project history
• Comparing options mentioned in different files

Don't use focus mode when:

• Quick fact lookup (phone number, command syntax)
• You need exact text matches
• Latency matters more than context quality

Installation: sqlite-vec (Optional)

For best performance, install sqlite-vec:

# macOS
brew install sqlite-vec

# Ubuntu/Debian
# Download from https://github.com/asg017/sqlite-vec/releases
# Place vec0.so in ~/.local/lib/ or /usr/local/lib/

Without it: Works fine, just slower on large databases.

File Structure

smart-memory/
├── smart_memory.js      # Main CLI
├── focus_agent.js       # Curated retrieval engine
├── memory_mode.js       # Mode toggle commands
├── memory.js            # OpenClaw wrapper
├── db.js                # SQLite layer
├── search.js            # Hybrid search
├── chunker.js           # Token-based chunking
├── embed.js             # Transformers.js embeddings
└── vector-memory.db     # SQLite database (auto-created)

Environment Variables

MEMORY_DIR=/path/to/memory        # Default: ./memory
MEMORY_FILE=/path/to/MEMORY.md    # Default: ./MEMORY.md
MEMORY_DB_PATH=/path/to/db.sqlite # Default: ./vector-memory.db

Comparison: v1 vs v2 vs v2.1

	v1 (JSON)	v2 (SQLite)	v2.1 (Focus Agent)
Search	Vector only	Hybrid (BM25 + Vector)	Hybrid + Focus Curation
Storage	JSON file	SQLite	SQLite
Scale	~1000 chunks	Unlimited	Unlimited
Keyword match	Weak	Strong (FTS5)	Strong (FTS5)
Context curation	No	No	Yes (toggle)
Setup	Zero config	Zero config	Zero config

License

MIT