@harper/openclaw-memory

Distributed long-term agent memory backed by Harper Cortex. Server-side embeddings, multi-agent sharing, zero API keys required.

Features

• Distributed persistence — Memories survive agent restarts and scale horizontally
• Server-side embeddings — Cortex handles embedding via ONNX (no API keys needed)
• Multi-agent sharing — Multiple agents can query the same memory pool with optional isolation
• Real database — ACID guarantees, queryable externally, backed by Harper Cortex
• Zero configuration — Unlike LanceDB, no local model downloads or dependency hell
• Automatic recall — Relevant memories injected as context before each agent turn
• Automatic capture — Facts extracted and stored after each turn
• Explicit tools — Agents can manually recall, store, and forget memories

Installation

npm install @harper/openclaw-memory

Then configure in your OpenClaw settings file:

{
  "plugins": {
    "slots": {
      "memory": "@harper/openclaw-memory"
    },
    "@harper/openclaw-memory": {
      "instanceUrl": "https://my-instance.harpercloud.com",
      "table": "agent_memory",
      "token": "optional-auth-token",
      "recallLimit": 3,
      "recallThreshold": 0.3,
      "captureLimit": 3,
      "dedupThreshold": 0.95
    }
  }
}

Or install via OpenClaw's plugin manager:

openclaw plugins install @harper/openclaw-memory

Configuration

Required

• instanceUrl — Harper Cortex instance URL (e.g., https://my-instance.harpercloud.com)

Optional

• token — Authentication token for Cortex (if instance requires auth)
• table — Cortex table for memory storage (default: agent_memory)
• schema — Cortex schema/database (default: data)
• agentId — Agent identifier for multi-agent isolation (tags all memories)
• recallLimit — Max memories retrieved per auto-recall (default: 3)
• recallThreshold — Minimum similarity for injection (default: 0.3, range: 0-1)
• captureLimit — Max facts extracted per turn (default: 3)
• dedupThreshold — Similarity threshold for dedup (default: 0.95, range: 0-1)

Usage

Automatic Recall (before_agent_start)

Before each agent turn, relevant memories are automatically searched and injected as context:

<relevant-memories>
- [fact] Python was created in 1989
- [preference] User likes concise answers
- [procedure] Always check the documentation first
</relevant-memories>

Automatic Capture (agent_end)

After each turn, the agent's response is analyzed to extract new facts and store them:

Agent: "The temperature in New York is 65°F."
→ Captures: [fact] "Temperature in New York is 65°F."

Explicit Tools

Agents can manually recall, store, and forget memories:

memory_recall

Search the memory pool by semantic similarity:

Input: {
  "query": "What's the user's preferred programming language?",
  "limit": 5,
  "minSimilarity": 0.3
}

Output: {
  "success": true,
  "results": [
    {
      "text": "User prefers Python for data analysis",
      "importance": 0.9,
      "category": "preference",
      "similarity": 0.87,
      "createdAt": "2026-03-19T10:30:00Z"
    }
  ],
  "count": 1
}

memory_store

Store a new fact or observation:

Input: {
  "text": "The user is interested in machine learning",
  "category": "preference",
  "importance": 0.8
}

Output: {
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Memory stored successfully (ID: 550e8400-e29b-41d4-a716-446655440000)"
}

memory_forget

Delete a memory (GDPR compliance, corrections):

Input: {
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Output: {
  "success": true,
  "message": "Memory 550e8400-e29b-41d4-a716-446655440000 deleted successfully"
}

CLI Commands

Stats

Show memory statistics:

openclaw memory stats

Output:

Memories stored: 42

Search

Search memories by semantic similarity:

openclaw memory search "Python programming" --limit 10 --threshold 0.5

Output:

Found 3 memory(ies):

1. [fact] (0.95) Python was created in 1989
   Importance: 0.8, Created: 2026-03-19T10:30:00Z

2. [preference] (0.82) User likes Pythonic code style
   Importance: 0.7, Created: 2026-03-18T14:22:00Z

3. [procedure] (0.78) Python best practice: use type hints
   Importance: 0.6, Created: 2026-03-17T09:15:00Z

Multi-Agent Isolation

The plugin supports three modes for multi-agent memory:

Option A: Table per agent

Each agent gets its own table:

{
  "table": "agent_memory_{agentId}"
}

Option B: Shared table with namespace (default)

Agents share a table but memories are tagged by agent:

{
  "table": "agent_memory",
  "agentId": "research-bot"
}

Cortex filters by agentId on search, ensuring isolation.

Option C: Shared memory pool

All agents read/write the same memories (team knowledge base):

{
  "table": "agent_memory"
}

Architecture

Core Components

• CortexMemoryDB — Low-level REST API client for Cortex
• Lifecycle Hooks — Auto-recall and auto-capture event handlers
• Memory Tools — Agent-callable functions for explicit memory ops
• Safety Module — Injection detection, content filtering, deduplication

Data Model

Each memory entry has:

{
  id: string;              // UUID
  text: string;            // The memory content
  importance: number;      // 0-1 importance score
  category: string;        // "fact" | "preference" | "procedure" | "event"
  agentId?: string;        // For multi-agent isolation
  createdAt: number;       // Timestamp (ms)
}

Security

The plugin includes built-in protections:

• Injection detection — Filters prompt injection markers, SQL-like patterns
• Content filtering — Removes control characters, normalizes Unicode
• Rate limiting — Optional rate limiter for API calls
• Deduplication — Avoids storing near-duplicate memories
• Validation — Type checks on importance, category, text length

Comparison with Alternatives

Feature	memory-lancedb	@harper/openclaw-memory
Embedding	Requires OpenAI API key	Server-side (Cortex ONNX)
Storage	Local file	Distributed service
Multi-agent	No (issue #2141)	Yes, isolated by agentId
Persistence	Dies with agent	Survives restarts
External query	No	Yes, via Cortex REST API
Scale	Single node	Horizontal (Harper clustering)
Install	Broken npm deps	Pure fetch, zero native deps

Development

Build

npm run build

Test

# Unit tests (mocked fetch)
npm test

# Integration tests (requires real Cortex instance)
export CORTEX_INSTANCE_URL=http://localhost:8080
npm run test:integration

Watch mode

npm run dev

Integration Testing

To run integration tests against a real Cortex instance:

1. Start Cortex:

   docker run -p 8080:8080 harperfast/cortex:latest

2. Set environment variables:

   export CORTEX_INSTANCE_URL=http://localhost:8080
   export CORTEX_TABLE=test_memories

3. Run tests:

   npm run test:integration

Troubleshooting

"Failed to store memory: 400 Bad Request"

Check that:

• Cortex instance is running and accessible
• instanceUrl is correct
• Table exists in Cortex schema
• Memory entry has text field (required)

"Failed to search memories: 404 Not Found"

Check that:

• MemorySearch endpoint is enabled on Cortex
• Table name matches Cortex schema
• Token is valid (if auth enabled)

No memories injected into context

Check that:

• Recall similarity threshold isn't too high (recallThreshold)
• Memories exist in Cortex table (use openclaw memory stats)
• Search results have similarity > threshold

Contributing

Contributions welcome! Please:

1. Fork the repo
2. Create a feature branch (git checkout -b feat/your-feature)
3. Write tests for new code
4. Run npm test and npm run lint
5. Submit a pull request

License

MIT

References

• Harper Cortex — Memory backend powering this plugin
• OpenClaw Plugin Docs — Plugin architecture
• Harper Fabric — The application platform behind Cortex