hermes-aidememo

Hermes Agent plugin for AideMemo (aidememo) — exposes the local knowledge graph as native tools, slash commands, and lifecycle hooks.

What you get

Install

# From a checkout, until the PyPI releases land:
HERMES_PY="${HERMES_PY:-$HOME/.hermes/hermes-agent/venv/bin/python3}"
"$HERMES_PY" -m pip install -e packages/aidememo-agent-sdk -e plugins/hermes

# After the PyPI releases:
"$HERMES_PY" -m pip install hermes-aidememo
"$HERMES_PY" -m pip install "hermes-aidememo[binding]"  # optional aidememo-python fast path

Use Hermes's own Python interpreter. Installing with an unrelated system python leaves the package outside Hermes's plugin host and the plugin will not be discovered.

Then enable it in ~/.hermes/config.yaml:

plugins:
  enabled:
    - aidememo
  aidememo:
    store_path: ~/.aidememo/wiki.sqlite   # optional; uses aidememo config default otherwise
    source_id: team-a               # optional default namespace for reads/writes
    actor_id: hermes:account-a      # optional writer provenance for new facts
    recent_window: 7d               # session_start auto-context window
    recent_limit: 10
    auto_capture:
      enabled: false                # opt-in; canonical writes remain explicit fact_add/SDK/MCP calls
      mode: pending                 # pending = review queue, direct = immediate write
      detect_in: both               # both | user | assistant
    confidence_floor: 0.85          # higher = stricter (fewer false positives)
    lock_retry_ms: 5000             # smooth over short local-store write contention
    default_entities: []            # legacy alias; prefer auto_capture.default_entities
    pending_log: ~/.hermes/state/aidememo-pending.jsonl  # review queue path

The plugin needs either aidememo-python (in-process binding) or the aidememo CLI binary on $PATH. The CLI fallback is always available — install from Git or build from source until the crates.io release lands.

Why a plugin instead of just the MCP server?

aidememo mcp-install --target hermes already works. The plugin route adds capabilities that MCP can't reach:

• Auto-context injection. Every new session gets the last week of facts pre-loaded — no tool call, no prompt, no model latency cost.
• Opt-in capture adapter. Decisions like "Decision: ship HNSW as default" or "결정: multilingual-128M로 가자" can be detected and queued to /aidememo-pending. Direct writes are available only when explicitly configured; the canonical path remains aidememo_fact_add, aidememo_fact_add_many, SDK remember(...), or MCP tool calls.
• Slash commands. /aidememo redis is one keypress vs the model picking to call aidememo_query.
• Low IPC overhead. When aidememo-python is installed, common hot-path calls (aidememo_workflow_start, aidememo_query, aidememo_context, aidememo_search, recent reads, and fact writes) run through direct Python bindings. MCP-only structured aggregate operations still use the CLI/MCP path until the binding exposes those slots.

Hermes-fit usage profiles

AideMemo is strongest when the Hermes task shape selects the memory behaviour, not when every turn uses the same generic retrieval call.

Memory-as-Code SDK

Use the SDK when a Hermes task needs more than one retrieval call and the intermediate candidate set should stay in Python objects instead of model tokens. For non-Hermes agents, import the same API from aidememo_agent.

from aidememo_agent import Memory

sdk = Memory.open(source_id="research-alpha", actor_id="hermes:researcher-a")

rows = sdk.search_rows([
    {"query": "Hermes top1_mass support gate", "tool": "search_query"},
    {"query": "Hermes patch browser_vision negative prior", "tool": "patch"},
])
coverage = sdk.coverage_by(rows, ["tool", "fact_type"])

sdk.remember([
    {
        "content": "Lesson: support-gated retrieval beats fixed prior residual on Hermes traces.",
        "fact_type": "lesson",
        "entities": ["Hermes", "SupportGate"],
    }
])

Configuration

Every key is optional; defaults are chosen for safety (high confidence floor, modest 7-day window, auto-capture off).

Recommended onboarding flow

For a wiki you care about, switch on pending capture for the first few sessions, then audit and selectively commit captures.

plugins:
  aidememo:
    auto_capture:
      enabled: true
      mode: pending

From chat (Hermes session):

/aidememo-start "Fix Redis timeout in worker" --body "Worker jobs time out" --source github:org/repo#123
/aidememo-context redis --source-id team-a    → broad opening context for a normal turn
/aidememo redis --source-id team-a       → query only team-a facts in a shared store
/aidememo-aggregate "Redis timeout decisions" --op count --type decision --source-id team-a
/aidememo-add "Redis cache policy is LRU" --entities Redis --source-id team-a
/aidememo-doctor                      → setup, source-scope, and shared-store diagnostics
/aidememo-pending                     → list every detection (numbered)
/aidememo-pending commit 3            → commit only entry #3
/aidememo-pending commit all          → commit all and clear the log
/aidememo-pending clear all           → discard everything

From a terminal (any agent — even non-Hermes):

aidememo pending review               # opens an interactive checklist TUI
                                #   space  cycle (commit / discard / —)
                                #   a      mark all for commit
                                #   c, ⏎   apply selections and exit
                                #   q, Esc cancel without changes

Failed commits are kept in the pending log so you can retry. If captures consistently look right and the team accepts immediate writes, switch auto_capture.mode to direct explicitly.

OpenClaw / generic hook adapter

Non-Hermes agents can use the same pending-first adapter by piping hook JSON into the standalone script:

scripts/aidememo-capture-adapter.py --enable --provider openclaw --mode pending \
  --pending-log ~/.openclaw/state/aidememo-pending.jsonl < hook-event.json

The script accepts generic keys such as messages, conversation, prompt/response, user_message/assistant_response, or raw text on stdin. Without --enable or AIDEMEMO_CAPTURE_ENABLE=1, it is read-only and reports that capture is disabled.

Development

cd plugins/hermes
python -m venv .venv
.venv/bin/pip install -e ".[test]"
.venv/bin/pytest
cd ../..
scripts/hermes-aidememo-pack-smoke.sh

Tests use a fake ctx so they run without a Hermes install. The pack smoke builds the wheel, installs it into a temp venv, and verifies the SDK export, Hermes plugin entry point, plugin.yaml, and bundled SKILL.md.

License

MIT OR Apache-2.0 (matches the AideMemo workspace).