Engram Memory

Persistent semantic memory for AI agents. Store, search, recall, and forget memories across sessions using Qdrant + FastEmbed.

Engram for OpenClaw Agents

Persistent semantic memory that makes your agent remember across sessions.

What This Provides

Instead of starting fresh every session, your agent will:

• Remember your preferences, facts, and past decisions
• Automatically recall relevant context for new conversations
• Search through stored memories semantically
• Categorize and organize knowledge by type

Quick Start

bash

# Install the skill
clawhub install engrammemory

# Setup (requires Docker — deploys Qdrant + FastEmbed)
bash scripts/setup.sh

# Store a memory
memory_store "I prefer direct communication style" --category preference

# Search memories
memory_search "communication preferences"

Core Functions

memory_store(text, category, importance)

Save information to long-term memory with semantic embedding.

python

# Save preferences
memory_store("User prefers TypeScript over JavaScript for new projects", 
            category="preference", importance=0.8)

# Save facts  
memory_store("Database migration completed on 2024-03-15, moved from SQLite to PostgreSQL",
            category="fact", importance=0.7)

# Save decisions
memory_store("Decided to use React Query for state management in the frontend",
            category="decision", importance=0.9)

memory_recall(query, limit, category)

Search stored memories using semantic similarity.

python

# Find relevant memories
memory_recall("database migration")
memory_recall("frontend preferences", category="preference")
memory_recall("recent decisions", limit=10)

memory_profile(action, key, value, category)

Manage user profile data (static preferences + dynamic context).

python

# View profile
memory_profile("view")

# Add static preference  
memory_profile("add", "communication_style", "Direct, no fluff", "static")

# Add dynamic context
memory_profile("add", "current_project", "Building memory system", "dynamic")

memory_forget(query, memory_id)

Remove memories by search or specific ID.

python

memory_forget("old project requirements")
memory_forget(memory_id="uuid-string")  

Memory Categories

• preference — User preferences, communication style, technical choices
• fact — Objective information, system states, completed work
• decision — Important decisions made, rationale, outcomes
• entity — People, projects, organizations, relationships
• other — Miscellaneous information that doesn't fit above

Context System

Engram includes a context management system that gives your agent structured knowledge about any codebase. Initialize a project, and your agent can search and query its architecture, patterns, and APIs.

Context Commands

engram-context — Core Management

bash

# Initialize context for a project
engram-context init /path/to/project --template web-app
engram-context init /path/to/project --template python-api
engram-context init /path/to/project --template generic

# Build search index
engram-context index

# Search context files
engram-context find "authentication patterns"

# Check status
engram-context status

engram-ask — Natural Language Queries

bash

engram-ask "How does authentication work?"
engram-ask "Where are the API endpoints defined?"
engram-ask interactive

engram-semantic — Embedding-Based Search

bash

engram-semantic find "user login process"
engram-semantic index
engram-semantic status

Project Templates

Template	Best for
web-app	Full-stack web apps (React/Vue + Node/Python + DB)
python-api	Python API servers (FastAPI, Django)
generic	Any project type

Context Structure

Each project gets a .context/ directory:

text

.context/
├── metadata.yaml       # Project configuration
├── architecture.md     # System architecture
├── patterns.md         # Code patterns and standards
├── apis.md             # API documentation
├── development.md      # Development workflows
├── troubleshooting.md  # Common issues and solutions
└── index.db            # Search index (auto-generated)

All context queries are scoped to the current project.

Architecture

text

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   OpenClaw      │    │  FastEmbed      │    │     Qdrant      │
│   Agent         │───▶│  nomic-embed    │───▶│  Vector Store   │
│                 │    │  text-v1.5      │    │  Port 6333      │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Components:

• Qdrant — Vector database for semantic storage/search
• FastEmbed — Local embedding model (nomic-embed-text-v1.5)
• Plugin — OpenClaw integration with auto-recall and capture

Installation

Prerequisites

• OpenClaw 2026.3.13+
• Docker and docker-compose
• 4GB+ RAM for embedding model
• 10GB+ storage for vector database

Automated Setup

bash

# 1. Install the skill
clawhub install engrammemory

# 2. Run setup script  
cd ~/.openclaw/workspace/skills/engrammemory
bash scripts/setup.sh

# 3. Follow the configuration prompts
# (The script will generate the exact config to add to openclaw.json)

# 4. Restart OpenClaw gateway
openclaw gateway restart

Manual Setup

If you prefer manual installation or need custom configuration:

1. Deploy Qdrant + FastEmbed:

   bash

   # Copy docker-compose template
   cp config/docker-compose.yml ~/engram-stack/
   cd ~/engram-stack
   docker-compose up -d
   

2. Configure OpenClaw plugin: Add to ~/.openclaw/openclaw.json:

   json

   {
     "plugins": {
       "allow": ["engram"],
       "slots": {
         "memory": "engram"
       },
       "entries": {
         "engram": {
           "enabled": true,
           "config": {
             "qdrantUrl": "http://localhost:6333",
             "embeddingModel": "nomic-ai/nomic-embed-text-v1.5",
             "collection": "agent-memory", 
             "autoRecall": true,
             "autoCapture": true,
             "maxRecallResults": 5,
             "minRecallScore": 0.35,
             "embeddingUrl": "http://localhost:11435"
           }
         }
       }
     }
   }
   

3. Restart gateway:

   bash

   openclaw gateway restart
   

Configuration Options

Option	Default	Description
qdrantUrl	http://localhost:6333	Qdrant vector database URL
embeddingUrl	http://localhost:11435	FastEmbed API endpoint
embeddingModel	nomic-ai/nomic-embed-text-v1.5	Embedding model
collection	agent-memory	Memory collection name
autoRecall	true	Auto-inject relevant memories
autoCapture	true	Auto-save important context
maxRecallResults	5	Max memories per auto-recall
minRecallScore	0.35	Minimum similarity threshold
profileFrequency	20	Update profile every N messages
debug	false	Enable debug logging

Example Configuration

json

{
  "qdrantUrl": "http://localhost:6333",
  "embeddingUrl": "http://localhost:11435",
  "collection": "agent-memory",
  "autoRecall": true,
  "autoCapture": true
}

Multi-Agent Setup

For multiple agents sharing memory:

json

{
  "agents": {
    "list": [
      {
        "id": "main",
        "plugins": {
          "memory": {
            "collection": "main-agent-memory"
          }
        }
      },
      {
        "id": "coding-assistant", 
        "plugins": {
          "memory": {
            "collection": "coding-agent-memory"
          }
        }
      }
    ]
  }
}

Usage Examples

Research Assistant

python

# Save research findings
memory_store("Found that React 18 concurrent rendering improves performance by 15-30% for large lists", 
            category="fact", importance=0.8)

# Later, when discussing performance:
memories = memory_recall("React performance improvements")
# Auto-recalls the research finding

Project Manager

python

# Save project decisions
memory_store("Team decided to use PostgreSQL over MongoDB for better ACID compliance in financial app",
            category="decision", importance=0.9)

# Track preferences
memory_profile("add", "deployment_preference", "Docker with Kubernetes", "static")

# Later project planning auto-recalls relevant decisions and preferences

Customer Support

python

# Remember customer preferences
memory_store("Customer prefers email over phone calls for non-urgent issues",
            category="preference", importance=0.7)

# Track issue patterns
memory_store("Billing module API timeout issue affects 15% of enterprise customers",
            category="fact", importance=0.8)

Backup and Migration

Export Memory

bash

# Export all memories as JSON
curl "http://localhost:6333/collections/agent-memory/points/scroll" \
  -H "Content-Type: application/json" \
  -d '{"limit": 10000}' > memory_backup.json

Import Memory

bash

# Import memories from backup
# Re-import using memory_store
python scripts/memory_store.py --json '{"text": "...", "category": "fact"}'

Performance Tuning

Vector Quantization (New Feature)

Engram now includes automatic scalar quantization for 4x memory reduction with no recall loss:

• Memory Usage: Reduces vector storage by ~75% (32-bit → 8-bit per dimension)
• Search Speed: Unchanged (quantized vectors stay in RAM for fast search)
• Quality: No degradation (99th percentile quantile preserves accuracy)
• Automatic: Enabled by default in new installations

bash

# Quantization is automatically applied when you run:
bash scripts/setup.sh

Technical Details:

• Uses int8 scalar quantization with 99th percentile
• Compresses 768-dimension vectors from ~3KB to ~768 bytes each
• Enables storing 4x more memories in the same RAM
• Fully compatible with existing memory collections

For Large Memory Sets (10K+ memories)

json

{
  "config": {
    "maxRecallResults": 3,
    "minRecallScore": 0.45,
    "autoCapture": false
  }
}

For High-Frequency Agents

json

{
  "config": {
    "profileFrequency": 50,
    "autoRecall": false
  }
}

Troubleshooting

Common Issues

Memory not persisting:

• Check Qdrant is running: curl http://localhost:6333/collections
• Verify plugin config in openclaw status

Poor recall quality:

• Lower minRecallScore (try 0.25)
• Check embedding model is loaded: curl http://localhost:11435/models

High memory usage:

• Increase Docker memory limits
• Reduce maxRecallResults
• Enable auto-cleanup in config

Debug Mode

json

{
  "config": {
    "debug": true
  }
}

Enables detailed logging for memory operations.

Advanced Usage

Custom Categories

python

memory_store("Customer uses advanced React patterns", category="customer_tech_profile")
memory_recall("customer tech preferences", category="customer_tech_profile")

Importance-Based Filtering

python

# Only recall highly important memories  
memory_recall("project decisions", min_importance=0.8)

Time-Based Queries

python

# Recent memories (last 30 days)
memory_recall("recent changes", days_back=30)

Security Considerations

• Local-first: All data stays on your infrastructure
• No external APIs: Embeddings generated locally
• Encryption: Use encrypted storage for sensitive data
• Access control: Configure Qdrant authentication if needed

Contributing

Found a bug or want to add features?

• GitHub: engram-memory-community
• Issues: Report bugs and feature requests
• Docs: Help improve documentation
• Examples: Share usage patterns

License

MIT License - Use freely in personal and commercial projects.

---

Transform your agent from stateless to stateful. Install Engram today.

OpenClaw Integration

🟢 Fully Integrated - Engram is now available as native OpenClaw tools.

Available Tools

• memory_search - Search memories using semantic similarity
• memory_store - Store text with embeddings in long-term memory

How to Use

Once Engram is set up (FastEmbed service + Qdrant running), these tools are automatically available in OpenClaw sessions:

javascript

// Search stored memories
memory_search("FastEmbed integration status", 10, 0.3)

// Store new memories
memory_store("User prefers detailed explanations", "preference", 0.8)

Implementation

• Plugin Type: Native Python plugin
• Backend: FastEmbed (localhost:8000) + Qdrant (localhost:6333)
• No MCP Server Required: Direct integration through OpenClaw's plugin system

See OPENCLAW_INTEGRATION.md for complete technical details.