jasper-recall 0.2.3 → 0.2.4

package/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: jasper-recall
-version: 0.2.1
-description: Local RAG system for agent memory using ChromaDB and sentence-transformers. Provides semantic search over session logs, daily notes, and memory files. v0.2.1 adds HTTP server for Docker-isolated agents. Commands: recall, index-digests, digest-sessions, privacy-check, sync-shared, serve.
+version: 0.2.3
+description: Local RAG system for agent memory using ChromaDB and sentence-transformers. Provides semantic search over session logs, daily notes, and memory files. v0.2.3 adds shared ChromaDB collections for multi-agent memory isolation. Commands: recall, index-digests, digest-sessions, privacy-check, sync-shared, serve.
 ---
 
-# Jasper Recall v0.2.1
+# 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.
@@ -111,7 +113,7 @@ Schedule regular indexing:
 }
 ```
 
-## Shared Agent Memory (v0.2.0)
+## Shared Agent Memory (v0.2.0+)
 
 For multi-agent setups where sandboxed agents need access to some memories:
 
@@ -125,6 +127,41 @@ 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:
+
+| Collection | Purpose | Who accesses |
+|------------|---------|--------------|
+| `private_memories` | Main agent's private content | Main agent only |
+| `shared_memories` | [public] tagged content | Sandboxed agents |
+| `agent_learnings` | Learnings from any agent | All agents |
+| `jasper_memory` | Legacy 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
@@ -159,8 +196,12 @@ recall "query" [OPTIONS]
 Options:
   -n, --limit N     Number of results (default: 5)
   --json            Output as JSON
-  -v, --verbose     Show similarity scores
-  --public-only     Only search shared/public content (v0.2.0+)
+  -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+)

package/cli/config.js

@@ -0,0 +1,145 @@
+/**
+ * Configuration management for jasper-recall
+ * 
+ * Priority: ENV vars > config file > defaults
+ * Config file: ~/.jasper-recall/config.json
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const CONFIG_DIR = path.join(os.homedir(), '.jasper-recall');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+const DEFAULTS = {
+  workspace: path.join(os.homedir(), '.openclaw', 'workspace'),
+  chromaDb: path.join(os.homedir(), '.openclaw', 'chroma-db'),
+  venv: path.join(os.homedir(), '.openclaw', 'rag-env'),
+  serverPort: 3458,
+  serverHost: '127.0.0.1',
+  publicOnly: true,  // Default for API access
+  memoryPaths: ['memory/'],
+  sharedMemoryPath: 'memory/shared/'
+};
+
+/**
+ * Load config from file
+ */
+function loadConfigFile() {
+  try {
+    if (fs.existsSync(CONFIG_FILE)) {
+      const raw = fs.readFileSync(CONFIG_FILE, 'utf8');
+      return JSON.parse(raw);
+    }
+  } catch (err) {
+    console.error(`Warning: Could not load config from ${CONFIG_FILE}:`, err.message);
+  }
+  return {};
+}
+
+/**
+ * Get config value with priority: ENV > file > default
+ */
+function get(key) {
+  const envMap = {
+    workspace: 'RECALL_WORKSPACE',
+    chromaDb: 'RECALL_CHROMA_DB',
+    venv: 'RECALL_VENV',
+    serverPort: 'RECALL_PORT',
+    serverHost: 'RECALL_HOST',
+    publicOnly: 'RECALL_PUBLIC_ONLY'
+  };
+
+  // Check env var first
+  const envKey = envMap[key];
+  if (envKey && process.env[envKey]) {
+    const val = process.env[envKey];
+    // Handle booleans
+    if (val === 'true') return true;
+    if (val === 'false') return false;
+    // Handle numbers
+    if (!isNaN(val)) return parseInt(val, 10);
+    return val;
+  }
+
+  // Check config file
+  const fileConfig = loadConfigFile();
+  if (key in fileConfig) {
+    return fileConfig[key];
+  }
+
+  // Return default
+  return DEFAULTS[key];
+}
+
+/**
+ * Get all config
+ */
+function getAll() {
+  const fileConfig = loadConfigFile();
+  const config = { ...DEFAULTS, ...fileConfig };
+  
+  // Override with env vars
+  for (const key of Object.keys(DEFAULTS)) {
+    config[key] = get(key);
+  }
+  
+  return config;
+}
+
+/**
+ * Save config to file
+ */
+function save(config) {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+  console.log(`Config saved to ${CONFIG_FILE}`);
+}
+
+/**
+ * Initialize config interactively
+ */
+function init(options = {}) {
+  const config = {
+    workspace: options.workspace || DEFAULTS.workspace,
+    chromaDb: options.chromaDb || DEFAULTS.chromaDb,
+    venv: options.venv || DEFAULTS.venv,
+    serverPort: options.serverPort || DEFAULTS.serverPort
+  };
+  
+  save(config);
+  return config;
+}
+
+/**
+ * Show current config
+ */
+function show() {
+  console.log('\nJasper Recall Configuration');
+  console.log('===========================\n');
+  console.log(`Config file: ${CONFIG_FILE}`);
+  console.log(`Exists: ${fs.existsSync(CONFIG_FILE) ? 'yes' : 'no'}\n`);
+  
+  const config = getAll();
+  for (const [key, value] of Object.entries(config)) {
+    const source = process.env[`RECALL_${key.toUpperCase()}`] ? '(env)' : 
+                   loadConfigFile()[key] !== undefined ? '(file)' : '(default)';
+    console.log(`  ${key}: ${value} ${source}`);
+  }
+  console.log('');
+}
+
+module.exports = {
+  CONFIG_DIR,
+  CONFIG_FILE,
+  DEFAULTS,
+  get,
+  getAll,
+  save,
+  init,
+  show,
+  loadConfigFile
+};

package/cli/jasper-recall.js

@@ -15,7 +15,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
-const VERSION = '0.2.3';
+const VERSION = '0.2.4';
 
 // Check for updates in background (non-blocking)
 const { checkInBackground } = require('./update-check');
@@ -139,9 +139,20 @@ COMMANDS:
   index       Index memory files (alias for index-digests)
   digest      Process session logs (alias for digest-sessions)
   serve       Start HTTP API server (for sandboxed agents)
+  config      Show or set configuration
   update      Check for updates
   help        Show this help message
 
+CONFIGURATION:
+  Config file: ~/.jasper-recall/config.json
+  
+  Environment variables (override config file):
+    RECALL_WORKSPACE   Memory workspace path
+    RECALL_CHROMA_DB   ChromaDB storage path
+    RECALL_VENV        Python venv path
+    RECALL_PORT        Server port (default: 3458)
+    RECALL_HOST        Server host (default: 127.0.0.1)
+
 EXAMPLES:
   npx jasper-recall setup
   recall "what did we discuss yesterday"
@@ -203,6 +214,18 @@ switch (command) {
       }
     });
     break;
+  case 'config':
+    // Configuration management
+    const config = require('./config');
+    const configArg = process.argv[3];
+    if (configArg === 'init') {
+      config.init();
+    } else if (configArg === 'path') {
+      console.log(config.CONFIG_FILE);
+    } else {
+      config.show();
+    }
+    break;
   case '--version':
   case '-v':
     console.log(VERSION);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jasper-recall",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Local RAG system for AI agent memory using ChromaDB and sentence-transformers",
   "main": "src/index.js",
   "bin": {

package/scripts/index-digests.py

@@ -2,6 +2,11 @@
 """
 Index markdown files into ChromaDB for RAG retrieval.
 Reads from memory/, session-digests/, repos/, and founder-logs/.
+
+v0.3.0: Multi-collection architecture
+- private_memories: main agent only (default)
+- shared_memories: accessible to sandboxed agents  
+- agent_learnings: insights from agent interactions (moltbook, etc.)
 """
 
 import os
@@ -56,8 +61,96 @@ def get_file_hash(content: str) -> str:
     return hashlib.md5(content.encode()).hexdigest()
 
 
+def determine_collection(rel_path: str, content: str) -> str:
+    """
+    Determine which collection a file belongs to based on path and content.
+    
+    Returns: 'private', 'shared', or 'learnings'
+    """
+    rel_lower = rel_path.lower()
+    content_lower = content.lower()
+    
+    # Agent learnings: moltbook insights, agent collaboration notes
+    if any(x in rel_lower for x in ['moltbook/', 'learnings/', 'agent-insights/']):
+        return 'learnings'
+    if '[learning]' in content_lower or '[insight]' in content_lower:
+        return 'learnings'
+    
+    # Shared: explicit shared folder or [public] tag
+    if 'shared/' in rel_lower:
+        return 'shared'
+    if '[public]' in content_lower:
+        return 'shared'
+    
+    # Default: private
+    return 'private'
+
+
+def index_to_collection(collection, model, filepath, rel_path, content, file_hash, stats):
+    """Index a file's chunks into a specific collection."""
+    filename = os.path.basename(filepath)
+    
+    # Check for existing chunks from this file
+    try:
+        existing = collection.get(
+            where={"source": rel_path},
+            include=[]
+        )
+    except Exception:
+        existing = {'ids': []}
+    
+    if existing['ids']:
+        # Check if hash matches (stored in first chunk's metadata)
+        try:
+            existing_meta = collection.get(
+                ids=[existing['ids'][0]],
+                include=["metadatas"]
+            )
+            if existing_meta['metadatas'] and existing_meta['metadatas'][0].get('file_hash') == file_hash:
+                stats['skipped'] += 1
+                return False
+        except Exception:
+            pass
+        
+        # File changed, delete old chunks
+        collection.delete(ids=existing['ids'])
+    
+    # Chunk the content
+    chunks = chunk_text(content)
+    
+    if not chunks:
+        return False
+    
+    # Generate embeddings
+    embeddings = model.encode(chunks).tolist()
+    
+    # Create IDs and metadata
+    ids = [f"{rel_path}::{i}" for i in range(len(chunks))]
+    metadatas = [
+        {
+            "source": rel_path,
+            "chunk_index": i,
+            "file_hash": file_hash,
+            "filename": filename,
+        }
+        for i in range(len(chunks))
+    ]
+    
+    # Add to collection
+    collection.add(
+        ids=ids,
+        embeddings=embeddings,
+        documents=chunks,
+        metadatas=metadatas
+    )
+    
+    stats['chunks'] += len(chunks)
+    stats['files'] += 1
+    return True
+
+
 def main():
-    print("🦊 Jasper Recall — RAG Indexer")
+    print("🦊 Jasper Recall — RAG Indexer v0.3.0")
     print("=" * 40)
     
     # Check if memory dir exists
@@ -75,12 +168,30 @@ def main():
     os.makedirs(CHROMA_DIR, exist_ok=True)
     client = chromadb.PersistentClient(path=CHROMA_DIR)
     
-    # Get or create collection
-    collection = client.get_or_create_collection(
+    # Create collections with descriptions
+    collections = {
+        "private": client.get_or_create_collection(
+            name="private_memories",
+            metadata={"description": "Private agent memories - main agent only"}
+        ),
+        "shared": client.get_or_create_collection(
+            name="shared_memories",
+            metadata={"description": "Shared memories - accessible to sandboxed agents"}
+        ),
+        "learnings": client.get_or_create_collection(
+            name="agent_learnings",
+            metadata={"description": "Agent learnings and insights from interactions"}
+        ),
+    }
+    
+    # Also maintain legacy collection for backwards compatibility
+    legacy_collection = client.get_or_create_collection(
         name="jasper_memory",
-        metadata={"description": "Agent session digests and memory files"}
+        metadata={"description": "Legacy collection - use specific collections instead"}
     )
     
+    print(f"✓ Collections: private_memories, shared_memories, agent_learnings")
+    
     # Gather files to index
     files_to_index = []
     
@@ -113,12 +224,23 @@ def main():
         files_to_index.extend(glob.glob(os.path.join(shared_dir, "*.md")))
         files_to_index.extend(glob.glob(os.path.join(shared_dir, "**/*.md"), recursive=True))
     
+    # Moltbook learnings
+    moltbook_dir = os.path.join(MEMORY_DIR, "shared", "moltbook")
+    if os.path.exists(moltbook_dir):
+        files_to_index.extend(glob.glob(os.path.join(moltbook_dir, "*.md")))
+    
+    # Remove duplicates while preserving order
+    files_to_index = list(dict.fromkeys(files_to_index))
+    
     print(f"Found {len(files_to_index)} files to index")
     
-    # Track stats
-    total_chunks = 0
-    indexed_files = 0
-    skipped_files = 0
+    # Track stats per collection
+    stats = {
+        "private": {"files": 0, "chunks": 0, "skipped": 0},
+        "shared": {"files": 0, "chunks": 0, "skipped": 0},
+        "learnings": {"files": 0, "chunks": 0, "skipped": 0},
+        "legacy": {"files": 0, "chunks": 0, "skipped": 0},
+    }
     
     for filepath in files_to_index:
         filename = os.path.basename(filepath)
@@ -134,69 +256,32 @@ def main():
         if not content.strip():
             continue
         
-        # Check if already indexed with same hash
         file_hash = get_file_hash(content)
         
-        # Check for existing chunks from this file
-        existing = collection.get(
-            where={"source": rel_path},
-            include=[]
-        )
+        # Determine target collection
+        coll_key = determine_collection(rel_path, content)
+        collection = collections[coll_key]
         
-        if existing['ids']:
-            # Check if hash matches (stored in first chunk's metadata)
-            existing_meta = collection.get(
-                ids=[existing['ids'][0]],
-                include=["metadatas"]
-            )
-            if existing_meta['metadatas'] and existing_meta['metadatas'][0].get('file_hash') == file_hash:
-                skipped_files += 1
-                continue
-            
-            # File changed, delete old chunks
-            collection.delete(ids=existing['ids'])
-        
-        # Chunk the content
-        chunks = chunk_text(content)
-        
-        if not chunks:
-            continue
-        
-        # Generate embeddings
-        embeddings = model.encode(chunks).tolist()
-        
-        # Determine visibility (public if in shared/ or contains [public] tag)
-        is_public = "shared/" in rel_path or "[public]" in content.lower()
-        visibility = "public" if is_public else "private"
-        
-        # Create IDs and metadata
-        ids = [f"{rel_path}::{i}" for i in range(len(chunks))]
-        metadatas = [
-            {
-                "source": rel_path,
-                "chunk_index": i,
-                "file_hash": file_hash,
-                "filename": filename,
-                "visibility": visibility
-            }
-            for i in range(len(chunks))
-        ]
+        # Index to the appropriate collection
+        indexed = index_to_collection(
+            collection, model, filepath, rel_path, content, file_hash, stats[coll_key]
+        )
         
-        # Add to collection
-        collection.add(
-            ids=ids,
-            embeddings=embeddings,
-            documents=chunks,
-            metadatas=metadatas
+        # Also index to legacy collection for backwards compatibility
+        index_to_collection(
+            legacy_collection, model, filepath, rel_path, content, file_hash, stats["legacy"]
         )
         
-        total_chunks += len(chunks)
-        indexed_files += 1
-        print(f"  ✓ {filename}: {len(chunks)} chunks")
+        if indexed:
+            print(f"  ✓ {filename} → {coll_key} ({stats[coll_key]['chunks']} chunks)")
     
     print("=" * 40)
-    print(f"✓ Indexed {indexed_files} files ({total_chunks} chunks)")
-    print(f"  Skipped {skipped_files} unchanged files")
+    print("✓ Indexing complete")
+    for key, s in stats.items():
+        if key == "legacy":
+            continue
+        if s['files'] > 0 or s['skipped'] > 0:
+            print(f"  {key}: {s['files']} files ({s['chunks']} chunks), {s['skipped']} skipped")
     print(f"  Database: {CHROMA_DIR}")
 
 

package/scripts/recall.py

@@ -1,7 +1,13 @@
 #!/usr/bin/env python3
 """
 RAG recall: Search agent memory for relevant context.
-Usage: recall "query" [--limit N] [--json] [--verbose]
+Usage: recall "query" [--limit N] [--json] [--verbose] [--collection NAME]
+
+v0.3.0: Multi-collection support
+- private_memories: main agent only (default for main agent)
+- shared_memories: accessible to sandboxed agents
+- agent_learnings: insights from agent interactions
+- all: search all collections (main agent only)
 """
 
 import os
@@ -13,9 +19,16 @@ import json
 CHROMA_DIR = os.environ.get("RECALL_CHROMA_DB", os.path.expanduser("~/.openclaw/chroma-db"))
 VENV_PATH = os.environ.get("RECALL_VENV", os.path.expanduser("~/.openclaw/rag-env"))
 
+# Collection names
+COLLECTIONS = {
+    "private": "private_memories",
+    "shared": "shared_memories",
+    "learnings": "agent_learnings",
+    "legacy": "jasper_memory",
+}
+
 # Activate the venv
 sys.path.insert(0, os.path.join(VENV_PATH, "lib/python3.12/site-packages"))
-# Also try python3.11, 3.10 for compatibility
 for pyver in ["python3.11", "python3.10"]:
     alt_path = os.path.join(VENV_PATH, f"lib/{pyver}/site-packages")
     if os.path.exists(alt_path):
@@ -30,13 +43,56 @@ except ImportError as e:
     sys.exit(1)
 
 
+def search_collection(collection, query_embedding, limit):
+    """Search a single collection and return results."""
+    try:
+        results = collection.query(
+            query_embeddings=[query_embedding],
+            n_results=limit,
+            include=["documents", "metadatas", "distances"]
+        )
+        return results
+    except Exception as e:
+        return None
+
+
+def merge_results(all_results, limit):
+    """Merge and sort results from multiple collections by similarity."""
+    merged = []
+    
+    for coll_name, results in all_results.items():
+        if not results or not results['documents'][0]:
+            continue
+        
+        for doc, meta, dist in zip(
+            results['documents'][0],
+            results['metadatas'][0],
+            results['distances'][0]
+        ):
+            merged.append({
+                "collection": coll_name,
+                "document": doc,
+                "metadata": meta,
+                "distance": dist,
+                "similarity": 1 - dist
+            })
+    
+    # Sort by similarity (descending)
+    merged.sort(key=lambda x: x['similarity'], reverse=True)
+    
+    return merged[:limit]
+
+
 def main():
     parser = argparse.ArgumentParser(description="Search agent memory")
     parser.add_argument("query", help="Search query")
     parser.add_argument("-n", "--limit", type=int, default=5, help="Number of results (default: 5)")
     parser.add_argument("--json", action="store_true", help="Output as JSON")
     parser.add_argument("-v", "--verbose", action="store_true", help="Show similarity scores")
-    parser.add_argument("--public-only", action="store_true", help="Only search public/shared content (for sandboxed agents)")
+    parser.add_argument("--public-only", action="store_true", 
+                        help="Only search shared content (for sandboxed agents)")
+    parser.add_argument("-c", "--collection", choices=["private", "shared", "learnings", "all", "legacy"],
+                        default=None, help="Specific collection to search (default: all for main, shared for --public-only)")
     args = parser.parse_args()
     
     if not os.path.exists(CHROMA_DIR):
@@ -47,61 +103,57 @@ def main():
     model = SentenceTransformer('all-MiniLM-L6-v2')
     client = chromadb.PersistentClient(path=CHROMA_DIR)
     
-    try:
-        collection = client.get_collection("jasper_memory")
-    except Exception:
-        print("❌ Collection not found. Run 'index-digests' first.", file=sys.stderr)
-        sys.exit(1)
+    # Determine which collections to search
+    if args.public_only:
+        # Sandboxed agents: only shared + learnings (public content)
+        if args.collection:
+            if args.collection not in ["shared", "learnings"]:
+                print(f"❌ --public-only restricts to 'shared' or 'learnings' collections", file=sys.stderr)
+                sys.exit(1)
+            search_collections = [args.collection]
+        else:
+            search_collections = ["shared", "learnings"]
+    elif args.collection:
+        if args.collection == "all":
+            search_collections = ["private", "shared", "learnings"]
+        else:
+            search_collections = [args.collection]
+    else:
+        # Default for main agent: search all collections
+        search_collections = ["private", "shared", "learnings"]
+    
+    # Get collections
+    collections_to_query = {}
+    for coll_key in search_collections:
+        coll_name = COLLECTIONS.get(coll_key, coll_key)
+        try:
+            collections_to_query[coll_key] = client.get_collection(coll_name)
+        except Exception:
+            # Collection doesn't exist yet, skip
+            pass
+    
+    if not collections_to_query:
+        # Fallback to legacy collection
+        try:
+            collections_to_query["legacy"] = client.get_collection("jasper_memory")
+        except Exception:
+            print("❌ No collections found. Run 'index-digests' first.", file=sys.stderr)
+            sys.exit(1)
     
     # Embed query
     query_embedding = model.encode([args.query])[0].tolist()
     
-    # Search with optional public-only filter
-    # Fetch extra results if filtering, since we'll post-filter
-    fetch_limit = args.limit * 3 if args.public_only else args.limit
+    # Search each collection
+    all_results = {}
+    for coll_key, collection in collections_to_query.items():
+        results = search_collection(collection, query_embedding, args.limit * 2)
+        if results:
+            all_results[coll_key] = results
     
-    query_params = {
-        "query_embeddings": [query_embedding],
-        "n_results": fetch_limit,
-        "include": ["documents", "metadatas", "distances"]
-    }
+    # Merge and limit results
+    merged = merge_results(all_results, args.limit)
     
-    results = collection.query(**query_params)
-    
-    # Post-filter for public-only mode
-    if args.public_only and results['documents'][0]:
-        filtered_docs = []
-        filtered_metas = []
-        filtered_dists = []
-        
-        for doc, meta, dist in zip(
-            results['documents'][0],
-            results['metadatas'][0],
-            results['distances'][0]
-        ):
-            source = meta.get('source', '')
-            visibility = meta.get('visibility', '')
-            
-            # Check if source is in shared/ folder OR has public visibility
-            is_shared = 'shared/' in source
-            is_public = visibility == 'public'
-            
-            # Reject if content contains [private] tag
-            has_private_tag = '[private]' in doc.lower()
-            
-            if (is_shared or is_public) and not has_private_tag:
-                filtered_docs.append(doc)
-                filtered_metas.append(meta)
-                filtered_dists.append(dist)
-                
-                if len(filtered_docs) >= args.limit:
-                    break
-        
-        results['documents'][0] = filtered_docs
-        results['metadatas'][0] = filtered_metas
-        results['distances'][0] = filtered_dists
-    
-    if not results['documents'][0]:
+    if not merged:
         if args.json:
             print("[]")
         else:
@@ -110,33 +162,29 @@ def main():
     
     if args.json:
         output = []
-        for i, (doc, meta, dist) in enumerate(zip(
-            results['documents'][0],
-            results['metadatas'][0],
-            results['distances'][0]
-        )):
+        for i, item in enumerate(merged):
             output.append({
                 "rank": i + 1,
-                "source": meta.get('source', 'unknown'),
-                "similarity": round(1 - dist, 3),  # Convert distance to similarity
-                "content": doc
+                "collection": item["collection"],
+                "source": item["metadata"].get("source", "unknown"),
+                "similarity": round(item["similarity"], 3),
+                "content": item["document"]
             })
         print(json.dumps(output, indent=2))
     else:
-        print(f"🔍 Results for: \"{args.query}\"\n")
+        searched = ", ".join(search_collections)
+        print(f"🔍 Results for: \"{args.query}\" (searched: {searched})\n")
         
-        for i, (doc, meta, dist) in enumerate(zip(
-            results['documents'][0],
-            results['metadatas'][0],
-            results['distances'][0]
-        )):
-            similarity = 1 - dist
+        for i, item in enumerate(merged):
+            similarity = item["similarity"]
             score_str = f" ({similarity:.1%})" if args.verbose else ""
-            source = meta.get('source', 'unknown')
+            source = item["metadata"].get("source", "unknown")
+            coll_tag = f"[{item['collection']}] " if len(search_collections) > 1 else ""
             
-            print(f"━━━ [{i+1}] {source}{score_str} ━━━")
+            print(f"━━━ [{i+1}] {coll_tag}{source}{score_str} ━━━")
             # Truncate long content
-            content = doc[:500] + "..." if len(doc) > 500 else doc
+            content = item["document"]
+            content = content[:500] + "..." if len(content) > 500 else content
             print(content)
             print()
 

package/scripts/write-learning.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""
+Write a learning to the agent_learnings collection.
+Designed for sandboxed agents to contribute back to shared memory.
+
+Usage:
+  write-learning "Brief title" "Learning content..."
+  write-learning --agent moltbook "Title" "Content"
+  write-learning --category engagement "Title" "Content"
+  write-learning --dry-run "Title" "Content"
+"""
+
+import os
+import sys
+import argparse
+import json
+import hashlib
+from datetime import datetime
+from pathlib import Path
+
+# Support custom paths via environment
+WORKSPACE = os.environ.get("RECALL_WORKSPACE", os.path.expanduser("~/.openclaw/workspace"))
+CHROMA_DIR = os.environ.get("RECALL_CHROMA_DB", os.path.expanduser("~/.openclaw/chroma-db"))
+VENV_PATH = os.environ.get("RECALL_VENV", os.path.expanduser("~/.openclaw/rag-env"))
+
+SHARED_DIR = os.path.join(WORKSPACE, "memory", "shared")
+LEARNINGS_FILE = os.path.join(SHARED_DIR, "agent-learnings.md")
+
+COLLECTION_LEARNINGS = "agent_learnings"
+
+# Activate the venv
+sys.path.insert(0, os.path.join(VENV_PATH, "lib/python3.12/site-packages"))
+for pyver in ["python3.11", "python3.10"]:
+    alt_path = os.path.join(VENV_PATH, f"lib/{pyver}/site-packages")
+    if os.path.exists(alt_path):
+        sys.path.insert(0, alt_path)
+
+try:
+    import chromadb
+    from sentence_transformers import SentenceTransformer
+except ImportError as e:
+    print(f"❌ Missing dependency: {e}", file=sys.stderr)
+    print("Run 'npx jasper-recall setup' to install dependencies.", file=sys.stderr)
+    sys.exit(1)
+
+
+def generate_id(title: str, agent: str, timestamp: str) -> str:
+    """Generate a unique ID for the learning."""
+    content = f"{agent}:{title}:{timestamp}"
+    return hashlib.md5(content.encode()).hexdigest()[:12]
+
+
+def append_to_learnings_file(title: str, content: str, agent: str, category: str, dry_run: bool = False):
+    """Append learning to the markdown file for human readability."""
+    os.makedirs(os.path.dirname(LEARNINGS_FILE), exist_ok=True)
+    
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M")
+    date = datetime.now().strftime("%Y-%m-%d")
+    
+    entry = f"\n## {date} [{category}] - {title}\n"
+    entry += f"*Agent: {agent} | {timestamp}*\n\n"
+    entry += f"{content}\n"
+    
+    if dry_run:
+        print("\n📄 Would append to agent-learnings.md:")
+        print("-" * 40)
+        print(entry)
+        return
+    
+    # Create file with header if it doesn't exist
+    if not os.path.exists(LEARNINGS_FILE):
+        with open(LEARNINGS_FILE, 'w') as f:
+            f.write("# Agent Learnings\n\n")
+            f.write("Insights and learnings contributed by sandboxed agents.\n\n")
+            f.write("---\n")
+    
+    # Append entry
+    with open(LEARNINGS_FILE, 'a') as f:
+        f.write(entry)
+    
+    print(f"📄 Added to {os.path.relpath(LEARNINGS_FILE, WORKSPACE)}")
+
+
+def index_to_chromadb(title: str, content: str, agent: str, category: str, dry_run: bool = False):
+    """Index the learning directly to ChromaDB."""
+    if dry_run:
+        print("\n🗄️ Would index to agent_learnings collection")
+        return
+    
+    # Initialize
+    os.makedirs(CHROMA_DIR, exist_ok=True)
+    client = chromadb.PersistentClient(path=CHROMA_DIR)
+    
+    collection = client.get_or_create_collection(
+        name=COLLECTION_LEARNINGS,
+        metadata={"description": "Learnings written by sandboxed agents"}
+    )
+    
+    # Load model
+    model = SentenceTransformer('all-MiniLM-L6-v2')
+    
+    # Prepare document
+    timestamp = datetime.now().isoformat()
+    doc_id = generate_id(title, agent, timestamp)
+    
+    # Combine title and content for embedding
+    full_text = f"{title}\n\n{content}"
+    embedding = model.encode([full_text])[0].tolist()
+    
+    metadata = {
+        "source": f"agent-learnings/{agent}/{doc_id}",
+        "filename": "agent-learnings.md",
+        "agent": agent,
+        "category": category,
+        "title": title,
+        "timestamp": timestamp,
+    }
+    
+    # Add to collection
+    collection.add(
+        ids=[doc_id],
+        embeddings=[embedding],
+        documents=[full_text],
+        metadatas=[metadata]
+    )
+    
+    print(f"🗄️ Indexed to {COLLECTION_LEARNINGS} (id: {doc_id})")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Write a learning to shared memory")
+    parser.add_argument("title", help="Brief title for the learning")
+    parser.add_argument("content", help="Learning content/description")
+    parser.add_argument("--agent", default="unknown", help="Agent name (e.g., moltbook, coder)")
+    parser.add_argument("--category", default="insight", 
+                       choices=["insight", "engagement", "pattern", "bug", "success", "failure"],
+                       help="Category of learning")
+    parser.add_argument("--dry-run", action="store_true", help="Preview without writing")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    
+    args = parser.parse_args()
+    
+    # Validate inputs
+    if len(args.title) > 200:
+        print("❌ Title too long (max 200 chars)", file=sys.stderr)
+        sys.exit(1)
+    
+    if len(args.content) > 5000:
+        print("❌ Content too long (max 5000 chars)", file=sys.stderr)
+        sys.exit(1)
+    
+    print(f"📝 Writing learning from agent '{args.agent}'...")
+    print(f"   Category: {args.category}")
+    print(f"   Title: {args.title}")
+    
+    if args.dry_run:
+        print("\n(DRY RUN - no changes will be made)")
+    
+    # Write to both file and ChromaDB
+    append_to_learnings_file(args.title, args.content, args.agent, args.category, args.dry_run)
+    index_to_chromadb(args.title, args.content, args.agent, args.category, args.dry_run)
+    
+    if not args.dry_run:
+        print("\n✅ Learning saved!")
+        
+        if args.json:
+            print(json.dumps({
+                "success": True,
+                "title": args.title,
+                "agent": args.agent,
+                "category": args.category
+            }))
+
+
+if __name__ == "__main__":
+    main()