{"_id":"hermes-memory-engine","_rev":"3-8072d653439d9b2d252dddffa6fa8a34","name":"hermes-memory-engine","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"hermes-memory-engine","version":"0.1.0","keywords":["ai","memory","markdown","llm","multi-agent","knowledge-base","sqlite","hermes"],"author":{"name":"Aiman","email":"aimanmalib@users.noreply.github.com"},"license":"MIT","_id":"hermes-memory-engine@0.1.0","maintainers":[{"name":"aimendev","email":"aimen.developer@gmail.com"}],"bin":{"hermes-memory":"dist/cli/index.js"},"dist":{"shasum":"25437b66f8f499c210fcbe43150769917d19d00c","tarball":"https://registry.npmjs.org/hermes-memory-engine/-/hermes-memory-engine-0.1.0.tgz","fileCount":11,"integrity":"sha512-ZTg7s68JObu3gIw3m9vsZg9PgFrwe5/6GryVIBhxDddMPDCRXV27HIMhmcZGQIKP31tJa1CznG2Vrp9tZChFvg==","signatures":[{"sig":"MEQCIGvKcVHisfBperPSok+e5xLns7d+xT8Zc+7VEsLN+HOZAiAmZl/8mmjfN7XrV9r/XNwx3L2TiNL9PMEGQlM5C89+aQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":566970},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./cli":"./dist/cli/index.js"},"gitHead":"cbd18a7c3e1afd8c1bc07e241968c6f0335edd52","scripts":{"dev":"tsup --watch","lint":"eslint src/ tests/","test":"vitest run","build":"tsup","docs:api":"typedoc","lint:fix":"eslint src/ tests/ --fix","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"aimendev","email":"aimen.developer@gmail.com"},"_npmVersion":"10.9.7","description":"Markdown-based AI memory system with multi-agent support, LLM-powered compression, and cloud sync","directories":{},"_nodeVersion":"22.22.2","dependencies":{"commander":"^13.0.0","gray-matter":"^4.0.3","better-sqlite3":"^11.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","eslint":"^9.0.0","vitest":"^3.0.0","typedoc":"^0.28.19","@eslint/js":"^9.39.4","typescript":"^5.6.0","@types/node":"^22.0.0","typescript-eslint":"^8.60.1","@vitest/coverage-v8":"^3.2.6","@types/better-sqlite3":"^7.6.13"},"_npmOperationalInternal":{"tmp":"tmp/hermes-memory-engine_0.1.0_1780765692750_0.6531781574956703","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"hermes-memory-engine","version":"0.1.1","keywords":["ai","llm","ai-agents","agent-memory","multi-agent","memory","markdown","sqlite","openai","anthropic","claude","hermes","typescript"],"author":{"name":"Muhammad Aiman"},"license":"MIT","_id":"hermes-memory-engine@0.1.1","maintainers":[{"name":"aimendev","email":"aimen.developer@gmail.com"}],"homepage":"https://github.com/aimanmalib/hermes-memory-engine#readme","bugs":{"url":"https://github.com/aimanmalib/hermes-memory-engine/issues"},"bin":{"hermes-memory":"dist/cli/index.js"},"dist":{"shasum":"69cb340ed11958ca8ab7502945dfd932adc9e627","tarball":"https://registry.npmjs.org/hermes-memory-engine/-/hermes-memory-engine-0.1.1.tgz","fileCount":11,"integrity":"sha512-GxfpNQPAGBMScTz9BZp16x2kG2nSb9lzqOUkSkiClYbbkqFWpWDCNb3g48WCxGk+PBt7kYMI9Bx7L5N9YFySAw==","signatures":[{"sig":"MEYCIQDrzWh3C7kpCd4kxPN5mmqZe0hvsNsLTMbv11NpM1abQQIhAKLmLP2PnL9I+N1Jg01u/t4xEp8torSEFl3F9YrWaIGT","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIHy/7L3o06iB9cd53VluBOQxiJxJwLseFA0FcEYfVn4kAiEAuOFUGZPIuuXQTVP8rgb7pZDCaliRw6pVP/JDQwJFX40=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/hermes-memory-engine@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":593937},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./cli":"./dist/cli/index.js"},"gitHead":"b91318f0f0be1d27e51d62fe77c73ffa53b2e514","scripts":{"dev":"tsup --watch","lint":"eslint . --max-warnings 0","test":"vitest run","build":"tsup","docs:api":"typedoc","lint:fix":"eslint . --fix","typecheck":"tsc --noEmit && tsc -p tsconfig.examples.json","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"e25d9d66-c37f-4bb9-9b49-50342e989df7"}},"overrides":{"js-yaml@3":{"argparse":"^2.0.1"}},"repository":{"url":"git+https://github.com/aimanmalib/hermes-memory-engine.git","type":"git"},"_npmVersion":"11.21.1","description":"Markdown-based AI memory system with multi-agent support, LLM-powered compression, and cloud sync","directories":{},"_nodeVersion":"22.23.3","dependencies":{"commander":"^13.0.0","gray-matter":"^4.0.3","better-sqlite3":"^11.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","eslint":"^9.39.5","vitest":"^5.0.5","typedoc":"^0.28.20","@eslint/js":"^9.39.5","typescript":"^5.6.0","@types/node":"^22.0.0","typescript-eslint":"^8.72.0","@vitest/coverage-v8":"^5.0.5","@types/better-sqlite3":"^7.6.13"},"_npmOperationalInternal":{"tmp":"tmp/hermes-memory-engine_0.1.1_1792644154632_0.833451369629514","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"_id":"hermes-memory-engine@0.2.0","bin":{"hermes-memory":"dist/cli/index.js"},"bugs":{"url":"https://github.com/aimanmalib/hermes-memory-engine/issues"},"dist":{"shasum":"231d89c80a94fe2b210514ef6df0d4932612a35c","tarball":"https://registry.npmjs.org/hermes-memory-engine/-/hermes-memory-engine-0.2.0.tgz","fileCount":11,"integrity":"sha512-iBCbPl2Fwzzjnu2+EjFm4eEs/HXKQJdDMxNAdNCCaITh4tm6kzl1A3misu3B5FoBolb7EJpqD5AyYiuuvRibNQ==","signatures":[{"sig":"MEUCIQCxkAdJYc9Yzf/wDeucH/NZy55zuoK0esf6iUg+RNfUngIgceCzbbqSOfWD89tSoE8BwKvcAP26U4olG7KZ77FekH0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDSUiYSNNULGOyQv7NyrSHC0Zi4/xuO7bSXgPKWvcbrBgIhAMrr0jmQys/JN7B8cjK4BG74hkDM1S5BrbBlY4fBI4yt"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/hermes-memory-engine@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":593682},"main":"./dist/index.cjs","name":"hermes-memory-engine","type":"module","types":"./dist/index.d.ts","author":{"name":"Muhammad Aiman"},"module":"./dist/index.js","engines":{"node":">=22.12.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./cli":"./dist/cli/index.js"},"gitHead":"ce45a817c24754ad79be780f4675d6ab2404ccd3","license":"MIT","scripts":{"dev":"tsup --watch","lint":"eslint . --max-warnings 0","test":"vitest run","build":"tsup","docs:api":"typedoc","lint:fix":"eslint . --fix","typecheck":"tsc --noEmit && tsc -p tsconfig.examples.json","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build"},"version":"0.2.0","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"e25d9d66-c37f-4bb9-9b49-50342e989df7"}},"homepage":"https://github.com/aimanmalib/hermes-memory-engine#readme","keywords":["ai","llm","ai-agents","agent-memory","multi-agent","memory","markdown","sqlite","openai","anthropic","claude","hermes","typescript"],"overrides":{"js-yaml@3":{"argparse":"^2.0.1"}},"repository":{"url":"git+https://github.com/aimanmalib/hermes-memory-engine.git","type":"git"},"_npmVersion":"11.21.1","description":"Markdown-based AI memory system with multi-agent support, LLM-powered compression, and cloud sync","directories":{},"maintainers":[{"name":"aimendev","email":"aimen.developer@gmail.com"}],"_nodeVersion":"22.23.3","dependencies":{"commander":"^15.0.0","gray-matter":"^4.0.3","better-sqlite3":"^11.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^9.0.0","eslint":"^9.39.5","vitest":"^5.0.5","typedoc":"^0.28.20","@eslint/js":"^9.39.5","typescript":"^5.6.0","@types/node":"^22.0.0","typescript-eslint":"^8.72.0","@vitest/coverage-v8":"^5.0.5","@types/better-sqlite3":"^7.6.13"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/hermes-memory-engine_0.2.0_1792759133676_0.7245924421741299"}}},"time":{"created":"2026-06-06T17:08:12.654Z","modified":"2026-10-23T12:38:54.134Z","0.1.0":"2026-06-06T17:08:12.883Z","0.1.1":"2026-10-22T04:42:34.707Z","0.2.0":"2026-10-23T12:38:53.762Z"},"bugs":{"url":"https://github.com/aimanmalib/hermes-memory-engine/issues"},"author":{"name":"Muhammad Aiman"},"license":"MIT","homepage":"https://github.com/aimanmalib/hermes-memory-engine#readme","keywords":["ai","llm","ai-agents","agent-memory","multi-agent","memory","markdown","sqlite","openai","anthropic","claude","hermes","typescript"],"repository":{"url":"git+https://github.com/aimanmalib/hermes-memory-engine.git","type":"git"},"description":"Markdown-based AI memory system with multi-agent support, LLM-powered compression, and cloud sync","maintainers":[{"name":"aimendev","email":"aimen.developer@gmail.com"}],"readme":"# Hermes Memory Engine\n\n[![CI](https://github.com/aimanmalib/hermes-memory-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/aimanmalib/hermes-memory-engine/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/hermes-memory-engine)](https://www.npmjs.com/package/hermes-memory-engine)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n**A markdown-based memory library for AI agents, written in TypeScript.** Memories are plain `.md` files with YAML frontmatter (or rows in SQLite), with building blocks for multi-agent namespaces, LLM-based compression, cloud sync, encryption and snapshots. It can also read and write the `MEMORY.md` / `USER.md` files used by Hermes Agent.\n\n> **Status:** early (0.x). The API may still change before 1.0.\n\n<p align=\"center\">\n  <img src=\"docs/demo/demo.gif\" alt=\"Terminal demo: hermes-memory init, add three memories for two agents, search, then list and print the Markdown files on disk\" width=\"900\">\n</p>\n<p align=\"center\"><sub>Real output from the published npm package (<code>npm i -g hermes-memory-engine</code>), recorded with <a href=\"https://github.com/charmbracelet/vhs\">VHS</a> from <a href=\"docs/demo/demo.tape\"><code>docs/demo/demo.tape</code></a>. Nothing is sped up.</sub></p>\n\n## Why?\n\nAI agents need persistent, searchable, structured memory. Flat `.md` files are easy to read but hard to query; vector databases are powerful but heavy. This library sits in between:\n\n- **Markdown-first** — one human-readable `.md` file per memory, grouped by agent\n- **Pluggable storage** — `FileBackend` or `SQLiteBackend` behind the same `MemoryStore` API\n- **Multi-agent** — per-agent namespaces, a shared pool with read/write/admin permissions, token-budgeted prompt context\n- **LLM compression** — summarize batches of old memories with any LLM (OpenAI and Claude adapters included)\n- **Sync** — push/pull to a GitHub Gist, S3-compatible storage, or your own HTTP endpoint\n- **Encryption** — AES-256-GCM helpers (scrypt key derivation) to encrypt memory content before you store or sync it\n- **Versioning** — in-memory snapshots with diff and rollback\n- **Integrations** — tool schemas and handlers for OpenAI and Claude tool calling; Hermes Agent import/export\n\n## Installation\n\n```bash\nnpm install hermes-memory-engine\n```\n\nRequires Node.js 22.12 or newer. SQLite support uses the native [`better-sqlite3`](https://github.com/WiseLibs/better-sqlite3) module, which is installed as a dependency.\n\n## Quick Start\n\n### CLI\n\nThe package ships a `hermes-memory` command. It stores memories in `./.hermes-memory` in the current directory.\n\n```bash\n# Create ./.hermes-memory\nnpx hermes-memory init\n\n# Add a memory (tags are comma-separated; agent defaults to \"default\")\nnpx hermes-memory add \"User prefers TypeScript and concise responses\" \\\n  --tags preferences,ui --agent my-agent\n\n# Search memories (optional: --tags, --agent, --limit)\nnpx hermes-memory search \"typescript\"\n\n# List recent memories (optional: --agent, --limit)\nnpx hermes-memory list\n\n# Import Hermes Agent's MEMORY.md / USER.md (default home: $HERMES_HOME or ~/.hermes)\nnpx hermes-memory import-hermes --home ~/.hermes\n\n# Export back to Hermes format — this OVERWRITES MEMORY.md and USER.md\nnpx hermes-memory export-hermes --home ~/.hermes\n\n# Demo only: runs compression with a mock LLM and prints the result; nothing is saved\nnpx hermes-memory compress --threshold 10\n```\n\n### Programmatic API\n\n```typescript\nimport { MemoryStore, FileBackend } from \"hermes-memory-engine\";\n\n// File-based storage (human-readable .md files)\nconst store = new MemoryStore(new FileBackend(\"./my-memories\"));\nawait store.init();\n\n// Create a memory\nconst memory = await store.create({\n  content: \"User prefers dark mode and concise responses\",\n  tags: [\"preferences\", \"ui\"],\n  agent: \"my-agent\",\n});\n\n// Filter by text, tags, agent or date range\nconst results = await store.search({\n  query: \"dark mode\",\n  tags: [\"preferences\"],\n  limit: 10,\n});\n\n// Read, update, list, delete\nawait store.get(memory.id);\nawait store.update(memory.id, { content: \"User prefers dark mode\" });\nawait store.listByAgent(\"my-agent\");\nawait store.delete(memory.id);\n```\n\n### SQLite backend\n\n```typescript\nimport { MemoryStore, SQLiteBackend } from \"hermes-memory-engine\";\n\nconst store = new MemoryStore(new SQLiteBackend(\"./memories.db\"));\nawait store.init();\n\n// Same API — swap backends without changing code\nawait store.create({ content: \"Stored in SQLite\", tags: [\"example\"] });\nawait store.close();\n```\n\n## Features\n\n### Relevance-scored search\n\n`MemoryStore.search` filters; `MemorySearch` ranks results by text match, tag boost and recency:\n\n```typescript\nimport { MemorySearch, MemoryStore, FileBackend } from \"hermes-memory-engine\";\n\nconst store = new MemoryStore(new FileBackend(\"./my-memories\"));\nawait store.init();\n\nconst ranked = new MemorySearch().search(await store.listAll(), {\n  query: \"dark mode\",\n  tagBoost: 2,\n  limit: 5,\n});\nranked.forEach((r) => console.log(r.score.toFixed(2), r.entry.content));\n```\n\n### Memory graph\n\nLink memories with typed relationships (`related_to`, `derived_from`, `supersedes`, `contradicts`, `supports`):\n\n```typescript\nimport { MemoryGraph, MemoryStore, FileBackend } from \"hermes-memory-engine\";\n\nconst store = new MemoryStore(new FileBackend(\"./my-memories\"));\nawait store.init();\nconst a = await store.create({ content: \"Project uses TypeScript\" });\nconst b = await store.create({ content: \"Project uses strict mode\" });\n\nconst graph = new MemoryGraph();\ngraph.addNode(a);\ngraph.addNode(b);\ngraph.addEdge(a.id, b.id, \"related_to\");\n\nconst related = graph.findRelated(a.id, 2); // BFS, max depth 2\nconst clusters = graph.getClusters(); // connected groups\n```\n\n### Multi-agent\n\n```typescript\nimport { AgentRegistry, AgentContext, SharedMemory, FileBackend } from \"hermes-memory-engine\";\n\n// Agents share one backend; each gets its own namespace\nconst registry = new AgentRegistry(new FileBackend(\"./agent-memories\"));\nawait registry.init();\n\nconst researcher = await registry.register({\n  id: \"researcher\",\n  name: \"Research Agent\",\n  canAccessShared: true,\n  canWriteShared: true,\n});\nawait researcher.store.create({ content: \"TypeScript adoption is growing\", agent: \"researcher\" });\n\n// Token-budgeted context for a system prompt\nconst ctx = new AgentContext(researcher.config, 2000);\nctx.loadMemories(await registry.getAgentMemories(\"researcher\"));\nconst systemPrompt = ctx.toSystemPrompt();\n\n// Shared pool with read / write / admin permissions\nconst shared = new SharedMemory(researcher.store);\nshared.grant(\"researcher\", \"write\");\nshared.grant(\"writer\", \"read\");\nawait shared.write(\"researcher\", \"Key finding: TS is growing\", [\"research\"]);\nconst visibleToWriter = await shared.read(\"writer\");\n```\n\n### LLM compression\n\n`MemoryCompressor` summarizes batches of memories with any `LLMProvider` (an object with `complete(prompt): Promise<string>`). It returns the summaries; saving them and removing the originals is up to you.\n\n```typescript\nimport { MemoryCompressor, OpenAIAdapter, MemoryStore, FileBackend } from \"hermes-memory-engine\";\n\nconst store = new MemoryStore(new FileBackend(\"./my-memories\"));\nawait store.init();\n\nconst llm = new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY ?? \"\" });\nconst compressor = new MemoryCompressor(llm);\n\n// For each agent with more than 20 memories, summarize the oldest ones\nconst results = await compressor.autoCompress(await store.listAll(), 20);\nfor (const r of results) {\n  await store.create({ content: r.compressed.content, tags: r.compressed.tags, agent: r.compressed.agent });\n}\n```\n\n### Cloud sync\n\n`MemorySync` takes a sync backend and a conflict strategy (`local`, `remote`, `merge` — the default — or `manual`):\n\n```typescript\nimport {\n  MemorySync,\n  GitHubGistBackend,\n  S3Backend,\n  HttpBackend,\n  MemoryStore,\n  FileBackend,\n} from \"hermes-memory-engine\";\n\nconst store = new MemoryStore(new FileBackend(\"./my-memories\"));\nawait store.init();\n\n// GitHub Gist (a new secret gist is created if no gistId is given)\nconst gistSync = new MemorySync(new GitHubGistBackend({ token: process.env.GITHUB_TOKEN ?? \"\" }), \"merge\");\nawait gistSync.sync(await store.listAll()); // merge local + remote, upload the result\n\n// S3-compatible storage (AWS S3, Cloudflare R2, MinIO, ...)\nconst s3Sync = new MemorySync(new S3Backend({ bucket: \"my-memories\", region: \"us-east-1\" }));\nconst { memories: remote } = await s3Sync.pull(); // fetch remote entries\n\n// Your own server (PUT/GET/HEAD/DELETE /memories)\nconst httpSync = new MemorySync(new HttpBackend({ url: \"https://example.com/api\", token: \"...\" }));\nawait httpSync.push(await store.listAll());\n```\n\n### Encryption\n\n```typescript\nimport { MemoryEncryption, MemoryStore, FileBackend } from \"hermes-memory-engine\";\n\nconst store = new MemoryStore(new FileBackend(\"./my-memories\"));\nawait store.init();\nconst memory = await store.create({ content: \"Sensitive fact\" });\n\nconst encryption = new MemoryEncryption();\nencryption.initWithPassphrase(\"my-secure-passphrase\"); // scrypt-derived AES-256-GCM key\n\nconst encrypted = encryption.encryptMemory(memory); // content encrypted, metadata.encrypted = true\nconst decrypted = encryption.decryptMemory(encrypted);\n\nconst batch = encryption.encryptMemories(await store.listAll());\n```\n\n### Versioning\n\nSnapshots are kept in memory; persist them yourself if you need them across restarts.\n\n```typescript\nimport { MemoryVersioning, MemoryStore, FileBackend } from \"hermes-memory-engine\";\n\nconst store = new MemoryStore(new FileBackend(\"./my-memories\"));\nawait store.init();\n\nconst versioning = new MemoryVersioning(50); // keep at most 50 snapshots\n\nconst before = versioning.commit(await store.listAll(), \"Before refactor\");\nawait store.create({ content: \"New fact\" });\nconst after = versioning.commit(await store.listAll(), \"After refactor\");\n\nconst diff = versioning.diff(before.id, after.id); // { added, removed, modified }\nconst restored = versioning.rollback(before.id); // memories as they were in that snapshot\n```\n\n### Integrations\n\n#### OpenAI / Claude adapters\n\nBoth adapters can act as the LLM provider for compression and expose memory tools for agent tool calling:\n\n```typescript\nimport { OpenAIAdapter, ClaudeAdapter, MemoryCompressor, MemoryStore, FileBackend } from \"hermes-memory-engine\";\n\nconst store = new MemoryStore(new FileBackend(\"./my-memories\"));\nawait store.init();\n\nconst openai = new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY ?? \"\" });\n\n// As LLM provider (for compression)\nconst compressor = new MemoryCompressor(openai);\n\n// As tool provider: memory_add, memory_search, memory_list\nconst tools = openai.getToolSchemas(); // OpenAI function-calling format\nconst result = await openai.handleToolCall(\"memory_add\", { content: \"fact\" }, store);\n\n// System prompt block with recent memories\nconst promptBlock = await openai.getSystemPromptBlock(store, \"my-agent\");\n\n// Same API for Claude (Anthropic Messages API; tool schemas use input_schema)\nconst claude = new ClaudeAdapter({ apiKey: process.env.ANTHROPIC_API_KEY ?? \"\" });\nconst claudeTools = claude.getToolSchemas();\n```\n\n#### Hermes Agent adapter\n\nRead and write Hermes Agent's `§`-separated `MEMORY.md` / `USER.md` files:\n\n```typescript\nimport { HermesMemoryAdapter, MemoryStore, FileBackend } from \"hermes-memory-engine\";\n\nconst store = new MemoryStore(new FileBackend(\"./my-memories\"));\nawait store.init();\n\n// hermesHome defaults to $HERMES_HOME or ~/.hermes\nconst hermes = new HermesMemoryAdapter({ hermesHome: \"/path/to/.hermes\" });\n\n// Import MEMORY.md + USER.md into the store\nconst imported = await hermes.importFromHermes(store);\n\n// Import, then write back (export overwrites the Hermes files)\nawait hermes.syncBidirectional(store, \"both\");\n```\n\n## Architecture\n\n```\n┌─────────────┐    ┌─────────────┐    ┌──────────────┐\n│  CLI / API  │───▶│ MemoryStore │───▶│   Backend    │\n│             │    │             │    │ File / SQLite│\n└─────────────┘    └──────┬──────┘    └──────────────┘\n                          │\n           ┌──────────────┼──────────────┐\n           ▼              ▼              ▼\n    ┌─────────────┐ ┌───────────┐ ┌────────────┐\n    │ MemoryGraph │ │  Agents   │ │  Sync/Enc  │\n    │ (relations) │ │ (multi)   │ │ (cloud)    │\n    └─────────────┘ └───────────┘ └────────────┘\n           │              │              │\n           └──────────────┼──────────────┘\n                          ▼\n                  ┌───────────────┐\n                  │ Integrations  │\n                  │ OpenAI/Claude │\n                  │ /Hermes       │\n                  └───────────────┘\n```\n\n**Design principles:**\n- **Pluggable backends** — implement `StorageBackend` or `SyncBackend` to add your own\n- **Small dependency footprint** — runtime dependencies are `better-sqlite3`, `gray-matter` and `commander`; HTTP calls use the built-in `fetch`\n- **Type-safe** — strict TypeScript, full type exports\n- **Human-readable** — markdown files you can inspect, diff and edit by hand\n\nDesign decisions are recorded in [`docs/adr/`](docs/adr).\n\n## CLI Reference\n\nAll commands use the store in `./.hermes-memory`.\n\n| Command | Options | Description |\n|---------|---------|-------------|\n| `hermes-memory init [dir]` | | Create the store directory (default `./.hermes-memory`) |\n| `hermes-memory add <content>` | `-t, --tags <tags>` · `-a, --agent <agent>` | Add a memory (tags comma-separated; agent defaults to `default`) |\n| `hermes-memory search <query>` | `-t, --tags` · `-a, --agent` · `-l, --limit` (10) | Search memories by text, tags and agent |\n| `hermes-memory list` | `-a, --agent` · `-l, --limit` (20) | List recent memories |\n| `hermes-memory import-hermes` | `--home <path>` | Import Hermes Agent `MEMORY.md` / `USER.md` |\n| `hermes-memory export-hermes` | `--home <path>` | Export to Hermes format (overwrites `MEMORY.md` / `USER.md`) |\n| `hermes-memory compress` | `-a, --agent` · `--threshold <n>` (5) | Demo of compression with a mock LLM; prints results, saves nothing |\n| `hermes-memory --version` / `--help` | | Show version / help |\n\n## Contributing\n\nDevelopment needs Node.js 22.12 or newer.\n\n1. Fork the repo\n2. `npm ci`\n3. `npm run typecheck && npm run lint && npm test`\n4. `npm run build`\n5. Open a PR (Conventional Commits, please)\n\nSecurity issues: see [SECURITY.md](SECURITY.md).\n\n## License\n\n[MIT](LICENSE) © Muhammad Aiman\n\n---\n\nBuilt by [Sasa Teguh](https://sasateguh.com) · Malaysia\n","readmeFilename":"README.md"}