Source Code

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:

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

How It Works

Hybrid Search Algorithm

FTS5 finds exact keyword matches (BM25 ranking)
Vector search finds semantic matches (cosine similarity)
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