Jasper Recall v0.2.3#

Local RAG (Retrieval-Augmented Generation) system for AI agent memory. Gives your agent the ability to remember and search past conversations.

New in v0.2.2: Shared ChromaDB Collections — separate collections for private, shared, and learnings content. Better isolation for multi-agent setups.

New in v0.2.1: Recall Server — HTTP API for Docker-isolated agents that can't run CLI directly.

New in v0.2.0: Shared Agent Memory — bidirectional learning between main and sandboxed agents with privacy controls.

When to Use#

• Memory recall: Search past sessions for context before answering
• Continuous learning: Index daily notes and decisions for future reference
• Session continuity: Remember what happened across restarts
• Knowledge base: Build searchable documentation from your agent's experience

Quick Start#

Setup#

One command installs everything:

bash

npx jasper-recall setup

This creates:

• Python venv at ~/.openclaw/rag-env
• ChromaDB database at ~/.openclaw/chroma-db
• CLI scripts in ~/.local/bin/
• OpenClaw plugin config in openclaw.json

Why Python?#

The core search and embedding functionality uses Python libraries:

• ChromaDB — Vector database for semantic search
• sentence-transformers — Local embedding models (no API needed)

These are the gold standard for local RAG. There are no good Node.js equivalents that work fully offline.

Why a Separate Venv?#

The venv at ~/.openclaw/rag-env provides:

BenefitWhy It MattersIsolationWon't conflict with your other Python projectsNo sudoInstalls to your home directory, no root neededClean uninstallDelete the folder and it's goneReproducibilitySame versions everywhere

The dependencies are heavy (~200MB total with the embedding model), but this is a one-time download that runs entirely locally.

Basic Usage#

Search your memory:

bash

recall "what did we decide about the API design"
recall "hopeIDS patterns" --limit 10
recall "meeting notes" --json

Index your files:

bash

index-digests  # Index memory files into ChromaDB

Create session digests:

bash

digest-sessions          # Process new sessions
digest-sessions --dry-run  # Preview what would be processed

How It Works#

Three Components#

1. digest-sessions — Extracts key info from session logs (topics, tools used)
2. index-digests — Chunks and embeds markdown files into ChromaDB
3. recall — Semantic search across your indexed memory

What Gets Indexed#

By default, indexes files from ~/.openclaw/workspace/memory/:

• *.md — Daily notes, MEMORY.md
• session-digests/*.md — Session summaries
• repos/*.md — Project documentation
• founder-logs/*.md — Development logs (if present)

Embedding Model#

Uses SkillBoss API Hub ( /v1/pilot embedding type) for vector embeddings:

• Automatically routes to optimal embedding model via SkillBoss API Hub
• No local model download required
• Requires SKILLBOSS_API_KEY environment variable

Agent Integration#

Memory-Augmented Responses#

python

# Before answering questions about past work
results = exec("recall 'project setup decisions' --json")
# Include relevant context in your response

Automated Indexing (Heartbeat)#

Add to HEARTBEAT.md:

markdown

## Memory Maintenance
- [ ] New session logs? → `digest-sessions`
- [ ] Memory files updated? → `index-digests`

Cron Job#

Schedule regular indexing:

json

{
  "schedule": { "kind": "cron", "expr": "0 */6 * * *" },
  "payload": {
    "kind": "agentTurn",
    "message": "Run index-digests to update the memory index"
  },
  "sessionTarget": "isolated"
}

Shared Agent Memory (v0.2.0+)#

For multi-agent setups where sandboxed agents need access to some memories:

Memory Tagging#

Tag entries in daily notes:

markdown

## 2026-02-05 [public] - Feature shipped
This is visible to all agents.

## 2026-02-05 [private] - Personal note
This is main agent only (default if untagged).

## 2026-02-05 [learning] - Pattern discovered
Learnings shared bidirectionally between agents.

ChromaDB Collections (v0.2.2+)#

Memory is stored in separate collections for isolation:

CollectionPurposeWho accessesprivate_memoriesMain agent's private contentMain agent onlyshared_memories[public] tagged contentSandboxed agentsagent_learningsLearnings from any agentAll agentsjasper_memoryLegacy unified (backward compat)Fallback

Collection selection:

bash

# Main agent (default) - searches private_memories
recall "api design"

# Sandboxed agents - searches shared_memories only
recall "product info" --public-only

# Search learnings only
recall "patterns" --learnings

# Search all collections (merged results)
recall "everything" --all

# Specific collection
recall "something" --collection private_memories

# Legacy mode (single collection)
recall "old way" --legacy

Sandboxed Agent Access#

bash

# Sandboxed agents use --public-only
recall "product info" --public-only

# Main agent can see everything
recall "product info"

Moltbook Agent Setup (v0.4.0+)#

For the moltbook-scanner (or any sandboxed agent), use the built-in setup:

bash

# Configure sandboxed agent with --public-only restriction
npx jasper-recall moltbook-setup

# Verify the setup is correct
npx jasper-recall moltbook-verify

This creates:

• ~/bin/recall — Wrapper that forces --public-only flag
• shared/ — Symlink to main workspace's shared memory

The sandboxed agent can then use:

bash

~/bin/recall "query"  # Automatically restricted to public memories

Privacy model:

1. Main agent tags memories as [public] or [private] in daily notes
2. sync-shared extracts [public] content to memory/shared/
3. Sandboxed agents can ONLY search the shared collection

Privacy Workflow#

bash

# Check for sensitive data before sharing
privacy-check "text to scan"
privacy-check --file notes.md

# Extract [public] entries to shared directory
sync-shared
sync-shared --dry-run  # Preview first

CLI Reference#

recall#

text

recall "query" [OPTIONS]

Options:
  -n, --limit N     Number of results (default: 5)
  --json            Output as JSON
  -v, --verbose     Show similarity scores and collection source
  --public-only     Search shared_memories only (sandboxed agents)
  --learnings       Search agent_learnings only
  --all             Search all collections (merged results)
  --collection X    Search specific collection by name
  --legacy          Use legacy jasper_memory collection

serve (v0.2.1+)#

text

npx jasper-recall serve [OPTIONS]

Options:
  --port, -p N    Port to listen on (default: 3458)
  --host, -h H    Host to bind (default: 127.0.0.1)

Starts HTTP API server for Docker-isolated agents.

Endpoints:
  GET /recall?q=query&limit=5    Search memories
  GET /health                    Health check

Security: public_only=true enforced by default.
Set RECALL_ALLOW_PRIVATE=true to allow private queries.

Example (from Docker container):

bash

curl "http://host.docker.internal:3458/recall?q=product+info"

privacy-check (v0.2.0+)#

text

privacy-check "text"     # Scan inline text
privacy-check --file X   # Scan a file

Detects: emails, API keys, internal IPs, home paths, credentials.
Returns: CLEAN or list of violations.

sync-shared (v0.2.0+)#

text

sync-shared [OPTIONS]

Options:
  --dry-run    Preview without writing
  --all        Process all daily notes

Extracts [public] tagged entries to memory/shared/.

index-digests#

text

index-digests

Indexes markdown files from:
  ~/.openclaw/workspace/memory/*.md
  ~/.openclaw/workspace/memory/session-digests/*.md
  ~/.openclaw/workspace/memory/repos/*.md
  ~/.openclaw/workspace/memory/founder-logs/*.md

Skips files that haven't changed (content hash check).

digest-sessions#

text

digest-sessions [OPTIONS]

Options:
  --dry-run    Preview without writing
  --all        Process all sessions (not just new)
  --recent N   Process only N most recent sessions

Configuration#

Custom Paths#

Set environment variables:

bash

export RECALL_WORKSPACE=~/.openclaw/workspace
export RECALL_CHROMA_DB=~/.openclaw/chroma-db
export RECALL_SESSIONS_DIR=~/.openclaw/agents/main/sessions

Chunking#

Default settings in index-digests:

• Chunk size: 500 characters
• Overlap: 100 characters

Security Considerations#

⚠️ Review these settings before enabling in production:

Server Binding#

The serve command defaults to 127.0.0.1 (localhost only). Do not use --host 0.0.0.0 unless you explicitly intend to expose the API externally and have secured it appropriately.

Private Memory Access#

The server enforces public_only=true by default. The env var RECALL_ALLOW_PRIVATE=true bypasses this restriction. Never set this on public/shared hosts — it exposes your private memories to any client.

autoRecall Plugin#

When autoRecall: true in the OpenClaw plugin config, memories are automatically injected before every agent message. Consider:

• Set publicOnly: true in plugin config for sandboxed agents
• Review which collections will be searched
• Use minScore to filter low-relevance injections

What's automatically skipped (no recall triggered):

• Heartbeat polls ( HEARTBEAT, Read HEARTBEAT.md, HEARTBEAT_OK)
• Messages containing NO_REPLY
• Messages < 10 characters
• Agent-to-agent messages (cron jobs, workers, spawned agents)
• Automated reports ( 📋 PR Review, 🤖 Codex Watch, ANNOUNCE_*)
• Messages from senders starting with agent: or worker-

Safer config for untrusted contexts:

json

"jasper-recall": {
  "enabled": true,
  "config": {
    "autoRecall": true,
    "publicOnly": true,
    "minScore": 0.5
  }
}

Environment Variables#

The following env vars affect behavior — set them explicitly rather than relying on defaults:

VariableDefaultPurposeRECALL_WORKSPACE``~/.openclaw/workspaceMemory files locationRECALL_CHROMA_DB``~/.openclaw/chroma-dbVector database pathRECALL_SESSIONS_DIR``~/.openclaw/agents/main/sessionsSession logsRECALL_ALLOW_PRIVATE``falseServer private accessRECALL_PORT``3458Server portRECALL_HOST``127.0.0.1Server bind address

Dry-Run First#

Before sharing or syncing, use dry-run options to preview what will be exposed:

bash

privacy-check --file notes.md     # Scan for sensitive data
sync-shared --dry-run             # Preview public extraction
digest-sessions --dry-run         # Preview session processing

Sandboxed Environments#

For maximum isolation, run jasper-recall in a container or dedicated account:

• Limits risk of accidental data exposure
• Separates private memory from shared contexts
• Recommended for multi-agent setups with untrusted agents

Troubleshooting#

"No index found"

bash

index-digests  # Create the index first

"Collection not found"

bash

rm -rf ~/.openclaw/chroma-db  # Clear and rebuild
index-digests

Model download slow First run downloads ~80MB model. Subsequent runs are instant.

Links#

• GitHub: https://github.com/E-x-O-Entertainment-Studios-Inc/jasper-recall
• npm: https://www.npmjs.com/package/jasper-recall
• ClawHub: https://clawhub.ai/skills/jasper-recall