hermes-brain-memory 0.1.0__py3-none-any.whl

hermes_brain_memory/__init__.py

@@ -0,0 +1,18 @@
+"""hermes-brain-memory — Brain Memory provider for Hermes Agent.
+
+This package is an *installer + payload*: it vendors the Brain Memory
+provider (a Hermes ``exclusive``/memory plugin, stdlib only) and ships the
+``hermes-brain-memory`` console script that copies it into
+``$HERMES_HOME/plugins/brain/``, where Hermes' user-plugin memory discovery
+picks it up.
+
+The provider itself lives in ``_vendor/brain/`` and is deliberately
+self-contained — Hermes loads it from the plugins directory, never through
+this package's import path.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

hermes_brain_memory/_vendor/brain/README.md

@@ -0,0 +1,51 @@
+# Brain Memory provider for Hermes Agent
+
+Backs Hermes Agent's memory slot with [Brain Memory](https://brainmemory.ai) — a local-first, human-readable Markdown memory store in `~/.brain/`, shared across Hermes, Claude Code, Codex, OpenCode, and OpenClaw. Memories decay, strengthen with use, and connect through an associative network — the model decides *what* to remember; the `brain` CLI handles the plumbing deterministically.
+
+## Requirements
+
+- The `brain` CLI: `npm install -g brain-memory` (then run its installer once so `~/.brain/` exists)
+- Python 3.10+ (no pip dependencies)
+
+## Setup
+
+1. Copy this directory to `$HERMES_HOME/plugins/brain/` (usually `~/.hermes/plugins/brain/`), or use it in-tree at `plugins/memory/brain/`.
+2. Activate it:
+
+```bash
+hermes memory setup        # guided
+```
+
+or in `~/.hermes/config.yaml`:
+
+```yaml
+memory:
+  provider: brain
+```
+
+3. Verify: `hermes memory status`
+
+## What it does
+
+| Lifecycle | Behavior |
+|---|---|
+| Session start | Injects a budget-bounded context block from `brain session-start`: status line, pinned facts, skills index, relevant memory titles, memorize guidance |
+| Pre-turn | Prefetches relevant memories for the user's message (background thread) |
+| Tools | `brain_recall` (recall + auto-reinforce + full bodies), `brain_memorize` (validated store), `brain_reinforce` |
+| Pre-compression | Reminds the model to store un-memorized notable content before context is discarded |
+| Session end | Appends a session entry to `~/.brain/contexts.json` (last 20 kept) |
+| Built-in memory writes | Mirrors MEMORY.md entries into `~/.brain` as deduplicated observations |
+
+## Configuration
+
+Stored in `$HERMES_HOME/brain.json`; environment variables override defaults.
+
+| Key | Default | Env var | Description |
+|---|---|---|---|
+| `project` | `hermes` | `BRAIN_PROJECT` | Project label for context-dependent recall |
+| `top_recall` | `6` | `BRAIN_TOP_RECALL` | Max memories per recall (1–25) |
+| `auto_reinforce` | `true` | `BRAIN_AUTO_REINFORCE` | Reinforce memories surfaced by `brain_recall` |
+| `brain_bin` | `brain` | `BRAIN_BIN` | Path to the brain CLI |
+| `sync_on_memorize` | `false` | `BRAIN_SYNC_ON_MEMORIZE` | Push each store to Brain Cloud / Git remote |
+
+The built-in MEMORY.md/USER.md memory keeps running alongside — this provider supplements it with a long-lived, cross-agent store. See `integrations/hermes/README.md` in the brain-memory repository for hooks-based and MCP-based alternatives.

hermes_brain_memory/_vendor/brain/__init__.py

@@ -0,0 +1,31 @@
+"""Brain Memory provider plugin for Hermes Agent.
+
+Local-first, human-readable Markdown memory (~/.brain) shared across Hermes,
+Claude Code, Gemini CLI, Codex, OpenCode, and OpenClaw. See README.md.
+"""
+
+try:
+    # Normal case: loaded as a package (in-tree plugins/memory/brain or
+    # $HERMES_HOME/plugins/brain when the loader imports the package).
+    from .provider import BrainMemoryProvider
+except ImportError:  # pragma: no cover
+    # Fallback: some loaders exec __init__.py as a standalone module, which
+    # breaks relative imports. Load provider.py from the same directory.
+    import importlib.util as _ilu
+    import os as _os
+
+    _spec = _ilu.spec_from_file_location(
+        "hermes_brain_memory_provider",
+        _os.path.join(_os.path.dirname(_os.path.abspath(__file__)), "provider.py"),
+    )
+    _mod = _ilu.module_from_spec(_spec)
+    assert _spec.loader is not None
+    _spec.loader.exec_module(_mod)
+    BrainMemoryProvider = _mod.BrainMemoryProvider
+
+__all__ = ["BrainMemoryProvider", "register"]
+
+
+def register(ctx) -> None:
+    """Register Brain Memory as a memory provider plugin."""
+    ctx.register_memory_provider(BrainMemoryProvider())

hermes_brain_memory/_vendor/brain/cli.py

@@ -0,0 +1,119 @@
+"""Standalone diagnostics CLI for the Brain Memory provider.
+
+Hermes loads user-installed memory providers through its memory-discovery
+path, whose plugin context only accepts ``register_memory_provider`` — it has
+no CLI registration (that API belongs to regular, non-exclusive plugins). So
+these commands run as a plain module instead:
+
+    python3 ~/.hermes/plugins/brain/cli.py status
+    python3 ~/.hermes/plugins/brain/cli.py recall "what did we decide about X"
+
+``register_cli(subparser)`` is kept for a possible future in-tree bundling
+where a real CLI hook exists. Stdlib only; shells out to the ``brain`` CLI
+(brain-memory npm package). In-session, use the provider's ``brain_recall`` /
+``brain_memorize`` tools — the agent calls those itself.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+try:
+    from .provider import BrainMemoryProvider, brain_dir
+except ImportError:  # pragma: no cover — standalone loading
+    import importlib.util as _ilu
+
+    _spec = _ilu.spec_from_file_location(
+        "hermes_brain_memory_provider_cli",
+        os.path.join(os.path.dirname(os.path.abspath(__file__)), "provider.py"),
+    )
+    _mod = _ilu.module_from_spec(_spec)
+    assert _spec.loader is not None
+    _spec.loader.exec_module(_mod)
+    BrainMemoryProvider = _mod.BrainMemoryProvider
+    brain_dir = _mod.brain_dir
+
+
+def _brain_bin() -> str:
+    return os.environ.get("BRAIN_BIN", "brain")
+
+
+def _cmd_status(args) -> int:
+    bin_name = _brain_bin()
+    found = shutil.which(bin_name) or (os.path.isfile(os.path.expanduser(bin_name)) and bin_name)
+    store = brain_dir()
+    index = store / "index.json"
+    print(f"brain CLI     : {found or 'NOT FOUND (npm install -g brain-memory)'}")
+    print(f"store         : {store} ({'present' if store.exists() else 'missing'})")
+    print(f"index.json    : {'present' if index.exists() else 'missing'}")
+    if found and index.exists():
+        try:
+            env = dict(os.environ)
+            env["BRAIN_AGENT"] = "hermes"
+            proc = subprocess.run(
+                [bin_name, "session-start", "--project", os.environ.get("BRAIN_PROJECT", "hermes")],
+                capture_output=True,
+                text=True,
+                timeout=15,
+                env=env,
+            )
+            if proc.returncode == 0:
+                payload = json.loads(proc.stdout)
+                print(f"memories      : {payload.get('memory_count', '?')}")
+                print(f"pinned        : {len(payload.get('pinned') or [])}")
+                print(f"skills        : {len(payload.get('skills_index') or [])}")
+        except (OSError, subprocess.TimeoutExpired, ValueError):
+            print("memories      : (could not query)")
+    return 0
+
+
+def _cmd_recall(args) -> int:
+    provider = BrainMemoryProvider()
+    provider.initialize("cli", hermes_home=os.environ.get("HERMES_HOME", ""))
+    print(
+        provider.handle_tool_call(
+            "brain_recall",
+            {"query": " ".join(args.query), "reinforce": False},
+        )
+    )
+    return 0
+
+
+def _dispatch(args) -> int:
+    command = getattr(args, "brain_command", None)
+    if command == "status":
+        return _cmd_status(args)
+    if command == "recall":
+        return _cmd_recall(args)
+    print("usage: hermes memory {status|recall <query>}")
+    return 1
+
+
+def register_cli(subparser) -> None:
+    """Attach brain subcommands to an argparse subparser (in-tree use only —
+    Hermes exposes no CLI hook to user-installed memory providers)."""
+    subs = subparser.add_subparsers(dest="brain_command")
+    subs.add_parser("status", help="Show Brain Memory store status")
+    recall = subs.add_parser("recall", help="Recall memories from ~/.brain")
+    recall.add_argument("query", nargs="+", help="What to recall")
+    subparser.set_defaults(func=_dispatch)
+
+
+def main(argv=None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        prog="brain-provider",
+        description="Brain Memory provider diagnostics (standalone)",
+    )
+    register_cli(parser)
+    args = parser.parse_args(argv)
+    return _dispatch(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hermes_brain_memory/_vendor/brain/plugin.yaml

@@ -0,0 +1,7 @@
+name: brain
+version: 1.0.0
+description: "Brain Memory — local-first, human-readable Markdown memory (~/.brain) with decay, spreading activation, and spaced reinforcement, shared across Hermes, Claude Code, Codex, OpenCode, and OpenClaw."
+hooks:
+  - on_session_end
+  - on_pre_compress
+  - on_memory_write