EntropicMem

EntropicMem: Standalone Agent Memory System

A self-contained knowledge engine for Hermes Agent. SQLite memory, Markdown vault, visual graph, and a 36-command knowledge loop. Install from the Hermes plugin catalog or via /learn.

Public repo. Never commit personal data: real names beyond the maintainer handle, home paths, emails, IPs, employer or client details, or memory/graph exports. See CONTRIBUTING.md for the rule and the pre-commit checklist.

What It Is

A Hermes Agent memory provider and skill delivering a complete, standalone knowledge system:

The v3 Line (In Development)

The storage and retrieval core is being rebuilt under plugins/entropicmem/scripts/em/ (schema v3, typed config). It lands behind flags and v3 stores; the v2 path above is unchanged until the owner-gated cutover. What has landed so far:

How the query-embedding seam works (EM-412). The provider builds one QueryEmbedder per session — only when embeddings.enabled is on and the store is v3 — and hands it to the three read sites. Every call runs the backend on a short-lived daemon thread the seam joins for at most timeout_s, default 20 s (matching openai_compat's per-call socket timeout, so the local backends gain the hard bound they shipped without). A raise, a timeout or an unavailable service returns None and the caller serves the lexical result — hard fail-soft, so an embed can neither break nor stall a search. A call arriving while a previous embed is still running past its bound fast-fails instead of queueing behind it, so a hung backend costs one bound, not one per search. Calls are counted per session and summarized at shutdown, so a potentially paid backend's usage stays visible. With the flag off — or on a v2 store — no backend is selected and the served paths are byte-identical.

Status and what's next: MASTER_TODO.md and docs/plan/REMAINING_PLAN.md.

Screenshots

Install

Option A: Hermes plugin catalog (recommended)

hermes plugins install entropicmem

Then wire the provider in ~/.hermes/config.yaml and bootstrap a vault:

memory:
  provider: entropicmem

python3 ~/.hermes/plugins/entropicmem/scripts/entropicmem.py init

Full detail: docs/SELF_INSTALL.md.

Option B: /learn skill flow

/learn https://github.com/Ufonik88/EntropicMem

The agent fetches the repo, installs the skill and plugin, bootstraps the vault, and smoke-tests in one pass. Follow skills/entropicmem/SETUP.md for the bootstrap checklist.

Quickstart

All commands run through the engine CLI under the plugin directory, python3 ~/.hermes/plugins/entropicmem/scripts/entropicmem.py:

python3 ~/.hermes/plugins/entropicmem/scripts/entropicmem.py init                       # Bootstrap vault + memory engine
python3 ~/.hermes/plugins/entropicmem/scripts/entropicmem.py ingest "https://..."       # One chunked note under Sources/ (+ pending claims)
python3 ~/.hermes/plugins/entropicmem/scripts/entropicmem.py query "topic" --top-k 10   # Cited vault search
python3 ~/.hermes/plugins/entropicmem/scripts/entropicmem.py recall "durable fact"      # Memory engine search
python3 ~/.hermes/plugins/entropicmem/scripts/entropicmem.py remember "durable fact"    # Store in memory engine
python3 ~/.hermes/plugins/entropicmem/scripts/entropicmem.py graph export --format html # Galaxy graph (./export/graph.html)

Repository Layout

EntropicMem/
├── plugins/entropicmem/         # Hermes MemoryProvider (9 tools, 6 hooks) + engine
│   ├── __init__.py              # Thin host shell (register + MemoryProvider import)
│   ├── config_schema.py         # Dashboard config schema (flat_json; EM-407)
│   ├── _backend.py              # Path resolution helpers
│   ├── plugin.yaml              # Catalog manifest
│   ├── scripts/                 # Engine + CLI (stdlib-only core)
│   │   ├── memory_engine.py     # SQLite FTS5 memory engine
│   │   ├── vault.py             # Markdown vault operations
│   │   ├── index.py             # Vault FTS5 index + graph edges
│   │   ├── retrieval.py         # Composed retrieval stack
│   │   ├── em/graph/            # Graph model, renderers + viewer assets (EM-605)
│   │   ├── graph_static.py      # Hardened stdlib server for `graph serve`
│   │   ├── policy.py / pii.py   # Write policy + PII redaction
│   │   ├── embeddings.py        # Vector search (optional)
│   │   ├── em/                  # v3 storage + retrieval core + typed config (in development)
│   │   ├── em_internal/         # The six shared-name engine modules (EM-212)
│   │   └── entropicmem.py       # CLI
│   └── README.md                # Plugin quick reference
├── skills/entropicmem/          # /learn skill: instructions + references + templates
│   ├── SKILL.md                 # Agent instructions (loaded by /learn)
│   ├── SETUP.md                 # First-run bootstrap checklist
│   ├── references/              # Agent-facing docs (memory model, integration)
│   └── templates/vault/         # Seed vault skeleton used by `init`
├── scripts/graph_server/        # FastAPI graph server (Host allowlist, CSP, token)
├── evals/                       # Eval framework: ci + hard suites, baselines, perf bench
├── benchmarks/                  # Frozen recall benchmark (corpus, probes, runner)
├── docs/                        # User-facing docs (see index below)
├── tests/                       # 2,000+ tests
└── .github/workflows/test.yml   # CI: pytest (3.10 to 3.13) + ruff + plugin validate

The engine lives under plugins/entropicmem/scripts/ so the plugin directory is self-contained: a catalog install (hermes plugins install entropicmem) carries the full engine with it. The skill directory holds only instructions, references, and vault templates.

Configuration

All settings live under plugins.entropicmem in ~/.hermes/config.yaml. Every key is optional; the schema is declared in plugins/entropicmem/config_schema.py and its defaults come from the typed model in plugins/entropicmem/scripts/em/config.py (EM-407). Dashboard-written settings arrive as $HERMES_HOME/entropicmem/config.json (flat JSON; one step in the read order).

plugins:
  entropicmem:
    vault_path: ~/.hermes/entropicmem/vault
    memory_db: ~/.hermes/entropicmem/memory.db
    prefetch_token_budget: 1500

Smart context details (how relevance scoring, dedup, and progressive disclosure work): skills/entropicmem/references/HERMES_INTEGRATION.md.

Memory Model

Five cooperating layers, full model in docs/MEMORY_MODEL.md:

Explainable recall: every recall(), recall_with_relevance(), and recall_hybrid() hit carries a why_retrieved field, a deterministic list of reason tokens (exact, fts, vector, recency, importance, triple, domain; the LIKE fallback path also reports fts) so you can audit why a fact surfaced. The entropicmem_search tool exposes it in its JSON output (why; the legacy why_retrieved key and the entropicmem_recall alias name are kept for one minor version).

Recall benchmark: run PYTHONPATH="plugins/entropicmem/scripts" python3 benchmarks/run_recall_bench.py to measure precision@5 and MRR against a frozen 98-fact corpus with 20 probes. CI enforces a floor (precision@5 >= 0.50, MRR >= 0.50).

Commands

37 top-level commands in 10 groups. Full reference: docs/CLI_REFERENCE.md. Invocations use python3 ~/.hermes/plugins/entropicmem/scripts/entropicmem.py <command>.

Hermes Integration

# ~/.hermes/config.yaml
memory:
  provider: entropicmem

• Interactive tools (nine): entropicmem_remember, entropicmem_search, entropicmem_update, entropicmem_forget, entropicmem_timeline, entropicmem_entity, entropicmem_profile, entropicmem_review, entropicmem_stats, plus the built-in memory tool. The legacy names (entropicmem_recall, entropicmem_query, entropicmem_patch_core, entropicmem_get, entropicmem_consolidate) route through an alias map for one minor version and report deprecated_tool in their responses.
• Prefetch injection: relevant facts are prefetched into <memory-context> each turn. These are system-injected context, not user input.
• Lifecycle hooks (6): on_memory_write mirrors built-in memory tool writes into the engine; on_session_switch tracks session state and resets caches — a rewound switch (host /undo) queues a retract_turns job that soft-deletes the undone turn's turn-stamped memories (restorable through entropicmem_review); on_session_end writes an extractive session digest episode (idempotent per session) and runs quarantine-first extraction; on_turn_start flushes a partial digest every N turns for always-on sessions; on_pre_compress checkpoints a standing-constraints digest before context compression (fail-closed checkpoint API v2); on_delegation records a redacted delegation episode and, on v3 stores, queues extraction over it with a 0.6 confidence cap. Config under plugins.entropicmem (session_end_capture, turn_cadence_flush_turns, turn_cadence_min_interval_sec, session_extract_pending), see docs/ARCHITECTURE.md.
• Cron: Hermes cron runs execute with memory writes disabled; persist durable facts through the CLI or the MemoryEngine API (deterministic, no LLM), never through interactive memory tools.
• Full integration guide: skills/entropicmem/references/HERMES_INTEGRATION.md.

Security

• Write policy: secret and credential content is blocked. High-confidence api_key / password findings are auto-redacted; other PII types are recorded as warn-only findings. Auto-extracted facts are quarantined as pending until promoted.
• Prompt-injection screen: vault retrieval and prefetch, recall, and get tool payloads pass a local injection screen. Flagged content ships with a prominent warning marker rather than being dropped (flag-with-warning, fail-open by design: if the screen itself fails, text ships unmarked).
• Vault path containment: vault writes are confined to the resolved vault root.
• Graph viewer: note markdown is sanitized against stored XSS (rendered HTML from marked and lazy-fetched bodies pass a client-side sanitize pass).
• Graph server: loopback-only bind enforced at startup; a non-loopback bind is refused unless ENTROPICMEM_GRAPH_EXPOSE=1 explicitly opts in, and read endpoints then require the X-EntropicMem-Token header. /refresh always requires the token. The token is ENTROPICMEM_GRAPH_TOKEN or, when unset, a random per-run token written owner-only to ~/.hermes/entropicmem/graph_server.token. A Host-header allowlist (DNS-rebinding guard) and a strict Content-Security-Policy apply to every response. entropicmem graph serve (stdlib, no token) enforces the same bind rule, Host allowlist and CSP, and serves only graph.html/graph.json. See docs/VISUALIZER.md.
• Destructive gates: forget and consolidate require --confirm; both auto-backup before running.
• Audit log: every write is append-only audited.
• Backups: AES-256-CBC encrypted before cloud upload. See docs/BACKUP_RESTORE.md.

Network Access

EntropicMem's memory engine, vault and Hermes integration run locally and make no network calls. These are the exceptions, and each is either opt-in or triggered by you:

Also: the shared publish store lives at $HERMES_HOME/entropicmem-shared/ (the root home in profile mode), and graph export writes to ./export in the current directory unless you pass --output-dir.

Known Limitations (2.8.x)

• Synonym / paraphrase recall. Retrieval is lexical (FTS5) unless the optional semantic stack is installed and enabled (embeddings_enabled: true). A query that shares no words with the stored fact ("what city am I based in?" against "The user lives in Cape Town") returns nothing. The hard eval suite's ageing category scores 0.733 recall@5 for exactly this reason; semantic retrieval is Sprint 3 (EM-303).
• Per-user isolation. owner_user_ids is an interim owner/guest guard. Fully scoped per-user storage (Alice cannot recall Bob's facts) is Sprint 4.
• Prefetch is synchronous. queue_prefetch is a no-op; prefetch runs inline on the caller (async prefetch is Sprint 4).
• Episodes are stored but not recalled. Session digests land in the timeline, but recall() does not surface them yet (Sprint 3).
• Validator warnings. hermes plugins validate prints two "declared but not registered" warnings for provides_tools/provides_hooks. They are kept on purpose: the Hermes catalog review verifies the plugin against those lists, and the warnings come from the validator not seeing tools a MemoryProvider exposes through get_tool_schemas().

These are pinned by strict xfail tests in tests/regressions/test_findings_v27.py, which will start failing (xpass) once each is fixed. On the v3 line, semantic retrieval (EM-303), episodes in recall and async prefetch (EM-403) have landed; per-user isolation remains open.

Documentation

Requirements

• Python 3.10+ (stdlib only for the core path)
• Optional: sentence-transformers for semantic search, graphviz for DOT export, fastapi + uvicorn for the graph server

License

MIT