#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
feat: add Hermes Agent memory provider plugin
Rohit Ghumare112e6f4bc07a
diff --git a/README.md b/README.mdindex 1aa7c4c6..576a54ee 100644--- a/README.md+++ b/README.md@@ -68,6 +68,7 @@ Start the memory server first: `npx @agentmemory/agentmemory`|---|---|| **Cursor** | Add to `~/.cursor/mcp.json`: `{"mcpServers": {"agentmemory": {"command": "npx", "args": ["agentmemory-mcp"]}}}` || **Gemini CLI** | `gemini mcp add agentmemory -- npx agentmemory-mcp` |+| **Hermes Agent** | Add to `~/.hermes/config.yaml`: `mcp_servers: {agentmemory: {command: npx, args: ["agentmemory-mcp"]}}` or use the [memory provider plugin](integrations/hermes/) || **OpenCode** | Add to `.opencode/config.json`: `{"mcpServers": {"agentmemory": {"command": "npx", "args": ["agentmemory-mcp"]}}}` || **Claude Desktop** | Add to `claude_desktop_config.json`: `{"mcpServers": {"agentmemory": {"command": "npx", "args": ["agentmemory-mcp"]}}}` || **Any agent (32+)** | `npx skillkit install agentmemory` |diff --git a/integrations/hermes/README.md b/integrations/hermes/README.mdnew file mode 100644index 00000000..dcd426b6--- /dev/null+++ b/integrations/hermes/README.md@@ -0,0 +1,72 @@+# agentmemory for Hermes Agent++Persistent cross-session memory for [Hermes Agent](https://github.com/NousResearch/hermes-agent) via agentmemory.++## Quick setup++### Option 1: MCP server (zero code)++Add to `~/.hermes/config.yaml`:++```yaml+mcp_servers:+ agentmemory:+ command: npx+ args: ["agentmemory-mcp"]+```++This gives Hermes access to all 43 MCP tools. Start the server separately:++```bash+npx @agentmemory/agentmemory+```++### Option 2: Memory provider plugin (deeper integration)++Copy this folder to your Hermes plugins directory:++```bash+cp -r integrations/hermes ~/.hermes/plugins/memory/agentmemory+```++Start the agentmemory server:++```bash+npx @agentmemory/agentmemory+```++The plugin auto-detects the running server and hooks into the Hermes agent loop:++- `prefetch()` injects relevant memories before each LLM call+- `sync_turn()` captures every conversation turn in the background+- `on_session_end()` marks sessions complete for summarization+- `on_pre_compress()` re-injects context before compaction+- `on_memory_write()` mirrors MEMORY.md writes to agentmemory+- `system_prompt_block()` injects project profile at session start++### Environment variables++| Variable | Default | Description |+|---|---|---|+| `AGENTMEMORY_URL` | `http://localhost:3111` | agentmemory server URL |+| `AGENTMEMORY_SECRET` | (none) | Auth token for protected instances |++## What Hermes gets++- 95.2% retrieval accuracy (LongMemEval-S, ICLR 2025)+- Hybrid search: BM25 + vector + knowledge graph+- Memory versioning, decay, and auto-forget+- Cross-agent: memories from Claude Code, Cursor, Gemini CLI all accessible+- Real-time viewer at http://localhost:3113++## How it works++Hermes has two memory files (MEMORY.md, USER.md) and SQLite full-text search. agentmemory adds structured memory on top:++| Hermes built-in | agentmemory adds |+|---|---|+| MEMORY.md (flat text) | Structured observations with facts, concepts, files |+| USER.md (preferences) | Project profiles with top patterns and conventions |+| SQLite FTS5 (session search) | BM25 + vector + knowledge graph (95.2% R@5) |+| Skills (self-improving) | Skill extraction from completed sessions |+| Single agent | Cross-agent memory via MCP + REST |diff --git a/integrations/hermes/__init__.py b/integrations/hermes/__init__.pynew file mode 100644index 00000000..863d4e49--- /dev/null+++ b/integrations/hermes/__init__.py@@ -0,0 +1,281 @@+"""+agentmemory memory provider for Hermes Agent.++Drop this folder into ~/.hermes/plugins/memory/agentmemory/+or install via: hermes plugin install agentmemory++Requires agentmemory server running: npx @agentmemory/agentmemory+"""++from __future__ import annotations++import json+import os+import threading+import time+from pathlib import Path+from typing import Any+from urllib.request import Request, urlopen+from urllib.error import URLError++try:+ from agent.memory_provider import MemoryProvider+except ImportError:+ from abc import ABC, abstractmethod++ class MemoryProvider(ABC):+ @property+ @abstractmethod+ def name(self) -> str: ...+ @abstractmethod+ def is_available(self) -> bool: ...+ @abstractmethod+ def initialize(self, session_id: str, **kwargs: Any) -> None: ...+ @abstractmethod+ def get_tool_schemas(self) -> list[dict]: ...+ @abstractmethod+ def handle_tool_call(self, name: str, args: dict) -> Any: ...+ def get_config_schema(self) -> list[dict]: return []+ def save_config(self, values: dict, hermes_home: str) -> None: pass+ def system_prompt_block(self) -> str: return ""+ def prefetch(self, query: str) -> str: return ""+ def queue_prefetch(self, query: str) -> None: pass+ def sync_turn(self, user: str, assistant: str) -> None: pass+ def on_session_end(self, messages: list) -> None: pass+ def on_pre_compress(self, messages: list) -> None: pass+ def on_memory_write(self, action: str, target: str, content: str) -> None: pass+ def shutdown(self) -> None: pass+++DEFAULT_BASE_URL = "http://localhost:3111"+TIMEOUT = 5+++def _api(base: str, path: str, body: dict | None = None, method: str = "POST") -> dict | None:+ url = f"{base}/agentmemory/{path}"+ headers = {"Content-Type": "application/json"}+ secret = os.environ.get("AGENTMEMORY_SECRET", "")+ if secret:+ headers["Authorization"] = f"Bearer {secret}"++ data = json.dumps(body).encode() if body else None+ req = Request(url, data=data, headers=headers, method=method)+ try:+ with urlopen(req, timeout=TIMEOUT) as resp:+ return json.loads(resp.read().decode())+ except (URLError, TimeoutError, json.JSONDecodeError):+ return None+++def _api_bg(base: str, path: str, body: dict | None = None) -> None:+ t = threading.Thread(target=_api, args=(base, path, body), daemon=True)+ t.start()+++class AgentMemoryProvider(MemoryProvider):++ @property+ def name(self) -> str:+ return "agentmemory"++ def is_available(self) -> bool:+ base = os.environ.get("AGENTMEMORY_URL", DEFAULT_BASE_URL)+ try:+ req = Request(f"{base}/", method="GET")+ with urlopen(req, timeout=2):+ return True+ except Exception:+ return False++ def initialize(self, session_id: str, **kwargs: Any) -> None:+ self._base = os.environ.get("AGENTMEMORY_URL", DEFAULT_BASE_URL)+ self._session_id = session_id+ self._project = kwargs.get("cwd", os.getcwd())+ self._secret = os.environ.get("AGENTMEMORY_SECRET", "")++ _api(self._base, "session/start", {+ "sessionId": session_id,+ "project": self._project,+ "cwd": self._project,+ })++ def get_config_schema(self) -> list[dict]:+ return [+ {+ "key": "url",+ "description": "agentmemory server URL",+ "default": DEFAULT_BASE_URL,+ "env_var": "AGENTMEMORY_URL",+ },+ {+ "key": "secret",+ "description": "agentmemory auth secret (optional)",+ "secret": True,+ "required": False,+ "env_var": "AGENTMEMORY_SECRET",+ },+ ]++ def save_config(self, values: dict, hermes_home: str) -> None:+ config_path = Path(hermes_home) / "agentmemory.json"+ config_path.write_text(json.dumps(values, indent=2))++ def system_prompt_block(self) -> str:+ result = _api(self._base, "context", {+ "sessionId": self._session_id,+ "project": self._project,+ })+ if result and result.get("context"):+ return result["context"]+ return ""++ def prefetch(self, query: str) -> str:+ result = _api(self._base, "smart-search", {+ "query": query,+ "limit": 5,+ })+ if not result or not result.get("results"):+ return ""++ lines = []+ for r in result["results"][:5]:+ obs = r.get("observation", r)+ title = obs.get("title", "")+ narrative = obs.get("narrative", "")+ if title:+ lines.append(f"- {title}: {narrative[:200]}")+ return "\n".join(lines) if lines else ""++ def queue_prefetch(self, query: str) -> None:+ _api_bg(self._base, "smart-search", {"query": query, "limit": 3})++ def get_tool_schemas(self) -> list[dict]:+ return [+ {+ "name": "memory_recall",+ "description": "Search agentmemory for past observations by keyword",+ "parameters": {+ "type": "object",+ "properties": {+ "query": {"type": "string", "description": "Search query"},+ "limit": {"type": "integer", "description": "Max results", "default": 10},+ },+ "required": ["query"],+ },+ },+ {+ "name": "memory_save",+ "description": "Save an insight, decision, or pattern to long-term memory",+ "parameters": {+ "type": "object",+ "properties": {+ "content": {"type": "string", "description": "What to remember"},+ "type": {+ "type": "string",+ "enum": ["pattern", "preference", "architecture", "bug", "workflow", "fact"],+ "description": "Memory type",+ },+ },+ "required": ["content"],+ },+ },+ {+ "name": "memory_search",+ "description": "Hybrid semantic + keyword search across all memories",+ "parameters": {+ "type": "object",+ "properties": {+ "query": {"type": "string"},+ "limit": {"type": "integer", "default": 5},+ },+ "required": ["query"],+ },+ },+ ]++ def handle_tool_call(self, name: str, args: dict) -> Any:+ if name == "memory_recall":+ result = _api(self._base, "search", {+ "query": args["query"],+ "limit": args.get("limit", 10),+ })+ if not result:+ return {"results": []}+ items = []+ for r in result.get("results", []):+ obs = r.get("observation", r)+ items.append({+ "title": obs.get("title", ""),+ "type": obs.get("type", ""),+ "narrative": obs.get("narrative", ""),+ "importance": obs.get("importance", 0),+ "timestamp": obs.get("timestamp", ""),+ })+ return {"results": items}++ if name == "memory_save":+ result = _api(self._base, "remember", {+ "content": args["content"],+ "type": args.get("type", "fact"),+ })+ return result or {"success": False}++ if name == "memory_search":+ result = _api(self._base, "smart-search", {+ "query": args["query"],+ "limit": args.get("limit", 5),+ })+ if not result:+ return {"results": []}+ items = []+ for r in result.get("results", []):+ obs = r.get("observation", r)+ items.append({+ "title": obs.get("title", ""),+ "narrative": obs.get("narrative", "")[:300],+ "score": r.get("combinedScore", r.get("score", 0)),+ })+ return {"results": items}++ return {"error": f"Unknown tool: {name}"}++ def sync_turn(self, user: str, assistant: str) -> None:+ _api_bg(self._base, "observe", {+ "hookType": "post_tool_use",+ "sessionId": self._session_id,+ "project": self._project,+ "cwd": self._project,+ "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),+ "data": {+ "tool_name": "conversation",+ "input": user[:500],+ "output": assistant[:2000],+ },+ })++ def on_session_end(self, messages: list) -> None:+ _api(self._base, "session/end", {+ "sessionId": self._session_id,+ })++ def on_pre_compress(self, messages: list) -> None:+ result = _api(self._base, "context", {+ "sessionId": self._session_id,+ "project": self._project,+ })+ if result and result.get("context"):+ pass++ def on_memory_write(self, action: str, target: str, content: str) -> None:+ if action in ("add", "update") and content:+ _api_bg(self._base, "remember", {+ "content": content,+ "type": "fact",+ })++ def shutdown(self) -> None:+ pass+++def register(ctx: Any) -> None:+ ctx.register_memory_provider(AgentMemoryProvider())diff --git a/integrations/hermes/plugin.yaml b/integrations/hermes/plugin.yamlnew file mode 100644index 00000000..b4f32151--- /dev/null+++ b/integrations/hermes/plugin.yaml@@ -0,0 +1,9 @@+name: agentmemory+version: 0.8.0+description: "Persistent cross-session memory for Hermes Agent via agentmemory. 95.2% retrieval accuracy on LongMemEval."+author: "Rohit Ghumare"+homepage: "https://github.com/rohitg00/agentmemory"+hooks:+ - on_session_end+ - on_pre_compress+ - on_memory_write