agentmemory Full Feature Deployment Log: From GitHub Trending to Four Platform Automatic Memory Capture

Background: Starting from GitHub Trending

On the morning of 2026-05-19, we found two highly relevant projects on the GitHub Trending weekly list (5/11-17):

#6 agentmemory (6,907⭐ → now 13K+): provides persistent memory for Claude Code, Cursor, OpenClaw, Hermes, and any MCP client
#2 superpowers (9,939⭐): one of the three-piece Meta-Skill suite we have installed

agentmemory's README directly lists native support for OpenClaw and Hermes, which caught our attention.

What is agentmemory?

agentmemory (rohitg00/agentmemory, Apache 2.0) is a persistent memory engine for AI coding agents. Core features:

Dimension	Details
Core engine	iii-engine (Rust), SQLite storage
Search method	BM25 + Vector + Graph hybrid search
Embedding model	all-MiniLM-L6-v2 (local, free, 384 dimensions)
Memory lifecycle	4-stage consolidation (Working→Episodic→Semantic→Procedural)
Memory decay	Ebbinghaus forgetting curve + automatic cleanup
Privacy filtering	Automatically strips API Key / Secret
Retrieval accuracy	LongMemEval-S R@5: 95.2%
Cost	~170K tokens/year ($0/year in local embedding mode)
External dependencies	Zero (no Qdrant/Postgres/vector database required)
NPM weekly downloads	15,500+
Version	v0.9.20 (42 releases, very frequent updates)

Architecture diagram

agentmemory server (localhost:3111)
    │
    ├── iii-engine (Rust core, SQLite)
    │   ├── BM25 full-text search
    │   ├── vector embeddings (all-MiniLM-L6-v2)
    │   └── knowledge graph (entity extraction + BFS)
    │
    ├── 4-layer memory consolidation
    │   Working → Episodic → Semantic → Procedural
    │
    ├── @agentmemory/mcp (MCP shim, 53 tools)
    │
    ├── real-time observer (localhost:3113)
    │
    └── multi-agent coordination (leases + signals + mesh)

Installation Process

Step 1: Start Server

npx @agentmemory/agentmemory

On first run, an interactive setup wizard starts:

Select Agent: Choose OpenClaw, Claude Code, Hermes
LLM Provider: Select Skip first (BM25-only), then connect OMLX later
III Engine: Automatically installs v0.11.2 (~6MB, 5 seconds)

Step 2: MCP Configuration

The setup wizard automatically writes the MCP configuration to each Agent's config file:

OpenClaw: ~/.openclaw/openclaw.json → mcp.servers.agentmemory
Claude Code: ~/.claude.json → mcpServers.agentmemory
Hermes: ~/.hermes/config.yaml → requires manual configuration (see below)

Step 3: Verification

curl http://localhost:3111/agentmemory/health
# {"status":"healthy","version":"0.9.20"}

# Real-time observer
open http://localhost:3113

Step 4: Demo Test

npx @agentmemory/agentmemory demo
# Automatically create 6 observations to verify semantic search

Full-feature upgrade: from BM25-only to a complete pipeline

After installation, the initial state is BM25-only (no LLM, no vector embeddings). Full-feature configuration is required:

Connect the local OMLX LLM

We run oMLX.app on Mac Studio (port 8888) as an OpenAI-compatible endpoint:

# ~/.agentmemory/.env
OPENAI_API_KEY=qwertyuiop
OPENAI_BASE_URL=http://localhost:8888/v1
OPENAI_MODEL=gemma-4-e2b-it-4bit

Enable all feature flags

# ~/.agentmemory/.env
EMBEDDING_PROVIDER=local          # Free local vector embeddings
AGENTMEMORY_TOOLS=all             # All 53 MCP tools
CONSOLIDATION_ENABLED=true        # 4-tier memory consolidation
GRAPH_EXTRACTION_ENABLED=true     # Knowledge graph extraction
AGENTMEMORY_AUTO_COMPRESS=true    # LLM auto-compression
AGENTMEMORY_INJECT_CONTEXT=true   # Automatic context injection
AGENTMEMORY_REFLECT=true          # Cross-memory reflection synthesis
BM25_WEIGHT=0.4                   # Hybrid search weight
VECTOR_WEIGHT=0.6
AGENTMEMORY_GRAPH_WEIGHT=0.2
TOKEN_BUDGET=3000

Final state

Health:       ✓ healthy
Provider:     ✓ llm (OMLX Gemma-4-e2b)
Embeddings:   ✓ local (all-MiniLM-L6-v2)
Consolidation ✓ 4-tier
Graph:        ✓ enabled
Auto-compress ✓ enabled
Context Inj.  ✓ enabled

Automatic Memory Capture Across Four Platforms

1. Claude Code (12 hooks, native plugin)

The setup wizard has already completed this automatically. The following was automatically added to ~/.claude.json:

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"]
    }
  }
}

Claude Code has the most complete integration:

12 lifecycle hooks: SessionStart/End, PreToolUse, PostToolUse, Notification, TaskCompleted, etc.
Automatic session management: each claude command automatically creates a session
Automatic observation capture: every prompt and every tool call is automatically recorded
Full pipeline triggering: consolidation → graph → lessons → dashboard

2. OpenClaw (Plugin hooks)

The Plugin must be installed manually:

# Download Plugin
mkdir -p ~/.openclaw/extensions/agentmemory
curl -sL https://raw.githubusercontent.com/rohitg00/agentmemory/main/integrations/openclaw/plugin.mjs \
  -o ~/.openclaw/extensions/agentmemory/plugin.mjs
# (also need openclaw.plugin.json, package.json, config.yaml)

Enable it in ~/.openclaw/openclaw.json:

{
  "plugins": {
    "slots": {
      "memory": "agentmemory"
    },
    "entries": {
      "agentmemory": {
        "enabled": true,
        "config": {
          "base_url": "http://localhost:3111",
          "token_budget": 2000
        }
      }
    }
  }
}

4 lifecycle hooks:

onSessionStart: inject relevant memory context
onPreLlmCall: query-aware refresh
onPostToolUse: record tool operations
onSessionEnd: summary + consolidation + graph

3. Hermes (6 hooks, manual configuration required)

Add the following to ~/.hermes/config.yaml:

mcp_servers:
  agentmemory:
    command: npx
    args: ["-y", "@agentmemory/mcp"]

memory:
  provider: agentmemory

6 lifecycle hooks: pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block.

4. DeepSeek TUI (native hooks)

DeepSeek TUI v0.8.37 has a built-in lifecycle hooks system. Configure it in ~/.deepseek/config.toml:

[hooks]
enabled = true

[[hooks.hooks]]
event = "session_start"
command = "bash ~/.deepseek/hooks/agentmemory.sh session_start"

[[hooks.hooks]]
event = "message_submit"
command = "bash ~/.deepseek/hooks/agentmemory.sh message_submit"

[[hooks.hooks]]
event = "tool_call_before"
command = "bash ~/.deepseek/hooks/agentmemory.sh tool_call_before"

[[hooks.hooks]]
event = "tool_call_after"
command = "bash ~/.deepseek/hooks/agentmemory.sh tool_call_after"

[[hooks.hooks]]
event = "session_end"
command = "bash ~/.deepseek/hooks/agentmemory.sh session_end"

[[hooks.hooks]]
event = "on_error"
command = "bash ~/.deepseek/hooks/agentmemory.sh on_error"

Hook script ~/.deepseek/hooks/agentmemory.sh:

#!/bin/bash
AGENTMEMORY="http://localhost:3111/agentmemory/mcp/call"
EVENT="${1:-unknown}"

curl -s -X POST "$AGENTMEMORY" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"memory_save\",\"arguments\":{\"content\":\"[DS-$EVENT] $(date)\",\"type\":\"fact\"}}" \
  > /dev/null 2>&1

Qdrant ↔ agentmemory Dual-Memory Architecture

We do not treat agentmemory as a replacement, but as complementary to the existing Qdrant vector memory (1,426 entries):

Qdrant (openclaw_mem)          agentmemory (localhost:3111)
    │                               │
    ├─ Business knowledge base (primary)    ├─ Coding agent memory (auxiliary)
    ├─ Research reports                     ├─ Session auto-capture
    ├─ Deal flow                            ├─ 4-layer memory consolidation
    ├─ Customer relationships               ├─ Knowledge graph
    └─ Manual mem_save                      └─ Automation + 53 tools

Sync Script

Created qdrant_to_agentmemory_sync.py to batch import through the agentmemory REST API:

# Core logic
def call_mcp(name, args):
    API = "http://localhost:3111/agentmemory/mcp/call"
    data = json.dumps({"name": name, "arguments": args}).encode()
    req = urllib.request.Request(API, data=data, headers={"Content-Type":"application/json"})
    # ...

# Selectively import high-value memories (research reports, legal compliance, transaction records)
for point in qdrant_points:
    call_mcp("memory_save", {
        "content": point.content,
        "type": infer_type(point.tags),
        "concepts": ",".join(point.concepts)
    })

53 MCP Tool Categories

Category	Count	Representative Tools
Core Memory	2	`memory_save`, `memory_recall`
Search and Retrieval	4	`memory_smart_search`, `memory_timeline`, `memory_vision_search`
Knowledge Graph	3	`memory_patterns`, `memory_relations`, `memory_graph_query`
Memory Management	6	`memory_consolidate`, `memory_compress_file`, `memory_profile`
Multi-Agent Coordination	11	`memory_action_create`, `memory_signal_send`, `memory_mesh_sync`
Diagnostics and Governance	7	`memory_diagnose`, `memory_heal`, `memory_audit`, `memory_verify`
Files and Export	3	`memory_export`, `memory_obsidian_export`, `memory_snapshot_create`
Learning and Reflection	5	`memory_lesson_save`, `memory_reflect`, `memory_sketch_create`
Other	12	`memory_facet_tag`, `memory_slot_*`, `memory_claude_bridge_sync`

LaunchAgent Persistence

To ensure agentmemory automatically recovers after a restart, a macOS LaunchAgent was created:

<!-- ~/Library/LaunchAgents/com.ultraclaw.agentmemory.plist -->
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
<key>WorkingDirectory</key>
<string>/Users/Claw/Library/Application Support/agentmemory</string>
<key>EnvironmentVariables</key>
<dict>
    <key>AGENTMEMORY_TOOLS</key><string>all</string>
    <key>PATH</key>
    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
</dict>

Persistent data is stored at ~/Library/Application Support/agentmemory/data/state_store.db.

Pitfall Log and Solutions

Pitfall 1: mcpServers vs mcp.servers Path Error

Problem: The installation wizard writes the configuration to mcpServers, but OpenClaw uses mcp.servers
Solution: Manually correct it to the correct path

Pitfall 2: Vector Dimension Conflict (2048 vs 384)

Problem: The old state store uses 2048-dimensional vectors, while the new local embedding is 384-dimensional
Error: Fatal: persisted vector index has wrong dimension
Solution: Set AGENTMEMORY_DROP_STALE_INDEX=true to discard the old vectors and rebuild

Pitfall 3: Node.js Version Conflict

Problem: /usr/local/bin/node (v22.14.0) in PATH takes precedence over /opt/homebrew/bin/node (v26.0.0)
Solution: brew upgrade node → 25.8.0 → 26.0.0; fix PATH priority

Pitfall 4: Large Data Volume Causes health critical

Problem: After a full import of 1,426 Qdrant memories, CPU spiked to 639%
Solution: Use selective import (high-value memories) and expand gradually

Pitfall 5: memory_save Does Not Trigger the Pipeline

Problem: memory_save is a standalone API and does not participate in the session→observation→consolidation pipeline
Impact: Dashboard / Graph / Lessons cannot be populated automatically
Solution: Enable native hooks (Claude Code / OpenClaw / Hermes) to automatically capture sessions; manually write lessons with memory_lesson_save

Pitfall 6: agentmemory Goes Offline After Gateway Restart

Problem: When OpenClaw Gateway restarts, it kills the agentmemory process
Solution: LaunchAgent's KeepAlive restarts it automatically

Final Architecture

                    ┌──────────────────────────┐
                    │   agentmemory v0.9.20    │
                    │   localhost:3111         │
                    │   ┌──────────────────┐   │
                    │   │ iii-engine (Rust)│   │
                    │   │ BM25+Vector+Graph│   │
                    │   │ 53 MCP tools     │   │
                    │   └──────────────────┘   │
                    └──────┬───────┬───────────┘
                           │       │
        ┌──────────────────┼───────┼──────────────────┐
        │                  │       │                  │
   ┌────▼─────┐    ┌──────▼──┐ ┌──▼──────┐   ┌──────▼──────┐
   │OpenClaw  │    │ Claude  │ │ Hermes  │   │ DeepSeek TUI│
   │Plugin 4  │    │ 12 hooks│ │ 6 hooks │   │ 6 hooks     │
   │hooks     │    │ auto    │ │ auto    │   │ auto save   │
   └──────────┘    └─────────┘ └─────────┘   └─────────────┘
                           │
                    ┌──────▼──────┐
                    │   Qdrant    │
                    │ 1,426 items │
                    │ Business KB │
                    └─────────────┘

Conclusion

agentmemory is a highly promising AI agent memory layer, particularly well suited to multi-agent collaboration scenarios. Its advantages are:

Zero external dependencies (SQLite + local embeddings), extremely simple deployment
High hybrid search accuracy (BM25 + Vector + Graph)
Native integration across multiple platforms (12+ agent support)
Complete memory lifecycle (4-layer consolidation + decay + graph)
53 MCP tools, covering everything from CRUD to multi-agent coordination

It forms a complementary architecture with Qdrant: Qdrant manages business knowledge, while agentmemory manages agent memory. Each excels in its own domain, and they bring out the best in each other.

Deployment date: 2026-05-19 | Author: Junze Think Tank