robrain 2.3.2 → 2.3.4

package/dist/lib/hermes-plugin.test.js

@@ -0,0 +1,54 @@
+// packages/cli/src/lib/hermes-plugin.test.ts
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, readdirSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+import { HermesPluginError, hermesPluginComplete, installHermesPlugin, resolveHermesHome, } from './hermes-plugin.js';
+function makePluginSource(root) {
+    const src = join(root, 'src-plugin');
+    mkdirSync(src, { recursive: true });
+    writeFileSync(join(src, '__init__.py'), '# provider\n');
+    writeFileSync(join(src, 'client.py'), '# client\n');
+    writeFileSync(join(src, 'plugin.yaml'), 'name: robrain\n');
+    writeFileSync(join(src, 'README.md'), '# docs\n');
+    mkdirSync(join(src, '__pycache__'));
+    writeFileSync(join(src, '__pycache__', 'junk.pyc'), '');
+    return src;
+}
+test('resolveHermesHome prefers HERMES_HOME env', () => {
+    assert.equal(resolveHermesHome({ HERMES_HOME: '/custom/home' }), '/custom/home');
+});
+test('resolveHermesHome defaults under the user home when env unset', () => {
+    const resolved = resolveHermesHome({});
+    assert.ok(resolved.includes('hermes'));
+});
+test('installs plugin into <home>/plugins/robrain, excluding __pycache__', () => {
+    const root = mkdtempSync(join(tmpdir(), 'hermes-plugin-'));
+    const src = makePluginSource(root);
+    const home = join(root, 'hermes-home');
+    const { dest } = installHermesPlugin(home, src);
+    assert.equal(dest, join(home, 'plugins', 'robrain'));
+    assert.ok(hermesPluginComplete(dest));
+    assert.ok(!readdirSync(dest).includes('__pycache__'));
+});
+test('replaces an existing install, including a dangling symlink', () => {
+    const root = mkdtempSync(join(tmpdir(), 'hermes-plugin-'));
+    const src = makePluginSource(root);
+    const home = join(root, 'hermes-home');
+    mkdirSync(join(home, 'plugins'), { recursive: true });
+    symlinkSync(join(root, 'nowhere'), join(home, 'plugins', 'robrain'));
+    const { dest } = installHermesPlugin(home, src);
+    assert.ok(hermesPluginComplete(dest));
+});
+test('throws when the source is missing or incomplete', () => {
+    const root = mkdtempSync(join(tmpdir(), 'hermes-plugin-'));
+    const incomplete = join(root, 'incomplete');
+    mkdirSync(incomplete);
+    writeFileSync(join(incomplete, '__init__.py'), '');
+    assert.throws(() => installHermesPlugin(join(root, 'home'), incomplete), HermesPluginError);
+    // '' = "resolution found nothing" — passing undefined would re-trigger the
+    // default resolver, which legitimately finds the real plugin in a monorepo.
+    assert.throws(() => installHermesPlugin(join(root, 'home'), ''), HermesPluginError);
+});
+//# sourceMappingURL=hermes-plugin.test.js.map

package/dist/lib/hermes-plugin.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hermes-plugin.test.js","sourceRoot":"","sources":["../../src/lib/hermes-plugin.test.ts"],"names":[],"mappings":"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"}

package/dist/lib/mcp-bundle.test.js

@@ -53,11 +53,11 @@ describe('materializeSensingBundle', () => {
     it('re-copies when the package version changed', () => {
         writeFakePackage(pkgDir, '2.2.0', 'old');
         assert.equal(materializeSensingBundle(pkgDir, mcpDir), true);
-        writeFakePackage(pkgDir, '2.3.2', 'new');
+        writeFakePackage(pkgDir, '2.3.4', 'new');
         assert.equal(materializeSensingBundle(pkgDir, mcpDir), true);
         assert.equal(readFileSync(join(mcpDir, 'sensing', 'dist', 'index.js'), 'utf8'), 'new');
         const marker = JSON.parse(readFileSync(join(mcpDir, 'sensing', 'package.json'), 'utf8'));
-        assert.equal(marker.version, '2.3.2');
+        assert.equal(marker.version, '2.3.4');
     });
     it('replaces a symlinked destination from a previous --repo-root install', () => {
         // Old dev install: ~/.robrain/mcp/sensing -> clone/packages/sensing-mcp

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "robrain",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "type": "module",
   "description": "RoBrain CLI for installation, setup, and memory workflows",
   "author": "Rory Plans, Inc.",
@@ -42,10 +42,10 @@
   },
   "scripts": {
     "build": "tsc",
-    "prepublishOnly": "pnpm build && node scripts/vendor-sensing-mcp.mjs",
+    "prepublishOnly": "pnpm build && node scripts/vendor-sensing-mcp.mjs && node scripts/vendor-hermes-plugin.mjs",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
-    "test": "pnpm build && node --test dist/lib/editor.codex.test.js dist/lib/mcp-bundle.test.js dist/commands/outcomes.test.js dist/commands/export-interchange.test.js dist/commands/up.test.js",
+    "test": "pnpm build && node --test dist/lib/editor.codex.test.js dist/lib/mcp-bundle.test.js dist/lib/claude-plugin.test.js dist/lib/hermes-plugin.test.js dist/commands/outcomes.test.js dist/commands/export-interchange.test.js dist/commands/up.test.js",
     "pack:verify": "node scripts/verify-publish-tarball.mjs",
     "postinstall": "node scripts/chmod-bin.cjs"
   },

package/scripts/vendor-hermes-plugin.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// Copy the Hermes memory-provider plugin into vendor/ so the published
+// robrain tarball can materialize it via `robrain install --hermes`
+// without a repo clone — same self-containment pattern as vendor-sensing-mcp.
+import { cpSync, existsSync, mkdirSync, rmSync } from 'fs'
+import { basename, dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+
+const cliRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
+const src = join(cliRoot, '..', '..', 'integrations', 'hermes', 'robrain')
+const dest = join(cliRoot, 'vendor', 'hermes-plugin', 'robrain')
+
+for (const required of ['__init__.py', 'client.py', 'plugin.yaml']) {
+  if (!existsSync(join(src, required))) {
+    console.error('vendor-hermes-plugin: missing', join(src, required))
+    process.exit(1)
+  }
+}
+
+rmSync(dest, { recursive: true, force: true })
+mkdirSync(dirname(dest), { recursive: true })
+cpSync(src, dest, {
+  recursive: true,
+  filter: p => basename(p) !== '__pycache__' && !p.endsWith('.pyc'),
+})
+console.log('Vendored Hermes plugin → packages/cli/vendor/hermes-plugin/robrain')

package/scripts/verify-publish-tarball.mjs

@@ -19,6 +19,7 @@ mkdirSync(work, { recursive: true })
 
 try {
   execFileSync('node', ['scripts/vendor-sensing-mcp.mjs'], { cwd: cliRoot, stdio: 'inherit' })
+  execFileSync('node', ['scripts/vendor-hermes-plugin.mjs'], { cwd: cliRoot, stdio: 'inherit' })
 
   execFileSync('pnpm', ['pack', '--pack-destination', work], { cwd: cliRoot, stdio: 'inherit' })
 
@@ -49,7 +50,27 @@ try {
     fail(`resolved dir has no dist/index.js: ${dir}`)
   }
 
-  console.log(`pack:verify ok — vendor resolves from ${dir}`)
+  const hermesVendorEntry = join(extracted, 'vendor', 'hermes-plugin', 'robrain', '__init__.py')
+  if (!existsSync(hermesVendorEntry)) {
+    fail('vendor/hermes-plugin/robrain/__init__.py missing from tarball')
+  }
+
+  const hermesUrl = pathToFileURL(join(extracted, 'dist', 'lib', 'hermes-plugin.js')).href
+  const { installHermesPlugin, resolveHermesPluginSourceDir } = await import(hermesUrl)
+  const hermesSrc = resolveHermesPluginSourceDir()
+  // realpath both sides — on macOS the tmpdir is reached via the /var →
+  // /private/var symlink, so raw prefix comparison false-negatives.
+  const { realpathSync } = await import('fs')
+  if (!hermesSrc || !realpathSync(hermesSrc).startsWith(realpathSync(extracted))) {
+    fail(`resolveHermesPluginSourceDir() did not resolve inside the tarball: ${hermesSrc}`)
+  }
+  const hermesHome = join(work, 'hermes-home')
+  const { dest } = installHermesPlugin(hermesHome)
+  if (!existsSync(join(dest, 'plugin.yaml'))) {
+    fail(`installHermesPlugin() copy incomplete at ${dest}`)
+  }
+
+  console.log(`pack:verify ok — sensing vendor resolves from ${dir}; hermes plugin installs from ${hermesSrc}`)
 } finally {
   rmSync(work, { recursive: true, force: true })
 }

package/vendor/hermes-plugin/robrain/README.md

@@ -0,0 +1,103 @@
+# RoBrain memory provider
+
+[RoBrain](https://github.com/adelinamart/robrain) is self-hosted decision
+memory: it passively captures what got decided in your sessions **and the
+alternatives you explicitly ruled out**, storing each veto as a structured
+`rejected[]` field (option + reason) in your own Postgres. Recall is ranked
+by a 5-signal composite score (semantic similarity, file overlap, recency,
+historical relevance, approval state). Nothing leaves your machine.
+
+The differentiator over fact-style memory: a rejection survives as data, not
+prose. When a task drifts toward something you already declined, the veto
+arrives in context as an explicit warning with the original reason —
+`REJECTED: Redis — second datastore to operate; ops budget is one datastore`.
+
+## What the provider does
+
+| Hermes hook | RoBrain behavior |
+|---|---|
+| system prompt | Injects the project's always-on summary (top decisions + vetoes) at session start |
+| prefetch | Background semantic retrieval per turn; rejected alternatives rendered as `REJECTED:` warnings |
+| sync_turn | Ships each turn to Perception, which runs its own server-side decision extraction — no local LLM, no extra API key |
+| `robrain_search` tool | On-demand decision + veto lookup before the agent commits to an approach |
+
+Fail-open: if the Perception API is down, recall degrades to nothing and
+writes are dropped with a log warning — the agent never blocks. Writes are
+skipped in cron/subagent contexts so system prompts never pollute the
+decision corpus. Previously injected memory context is stripped before
+capture, so recall can't re-enter the corpus as a fresh "decision".
+
+## Setup
+
+This is a **standalone Hermes plugin** — hermes-agent's contribution policy
+asks memory providers to ship outside their tree, installed into
+`$HERMES_HOME/plugins/` where Hermes' plugin discovery picks them up with
+the same lifecycle hooks as bundled providers.
+
+1. Run RoBrain (~2 minutes — [install guide](https://github.com/adelinamart/robrain#install)):
+
+   ```bash
+   # No clone:
+   npx robrain@latest up
+   # Or from a clone:
+   git clone https://github.com/adelinamart/robrain && cd robrain
+   pnpm install && pnpm build && pnpm docker:up
+   ```
+
+   Add `ANTHROPIC_API_KEY` and your embedding key to `~/.robrain/stack/.env` (after `robrain up`) or the repo `.env` (clone path), then ensure Perception is healthy: `curl -sf http://localhost:3001/health`.
+
+2. Install the plugin — no clone needed; the published CLI carries it:
+
+   ```bash
+   npx robrain@latest install --hermes
+   ```
+
+   (`$HERMES_HOME` defaults to `~/.hermes` on macOS/Linux; the command
+   respects the env var. From a repo clone, `cp -r
+   integrations/hermes/robrain "${HERMES_HOME:-$HOME/.hermes}/plugins/robrain"`
+   does the same thing.)
+
+3. Point Hermes at it:
+
+   ```bash
+   hermes memory setup    # select "robrain"
+   ```
+
+   You'll be asked for:
+   - **base_url** — Perception's URL (default `http://localhost:3001`)
+   - **project_id** — your RoBrain project (default `default`)
+   - **scope** — recorded on captured decisions (default `team`)
+   - **PERCEPTION_API_KEY** — from `~/.robrain/stack/.env` (after `robrain up`) or the repo `.env` (clone path)
+
+Config lands in `$HERMES_HOME/robrain/config.json` (non-secrets) and the
+profile env store (the key). Env fallbacks for headless setups:
+`ROBRAIN_BASE_URL`, `ROBRAIN_PROJECT_ID`, `PERCEPTION_API_KEY`.
+
+## Notes
+
+- Decisions captured from Hermes sessions land in the same Postgres store
+  RoBrain fills from Claude Code, Cursor, Copilot, and Codex CLI — one
+  shared decision memory across your tools. Review captures with
+  `npx robrain review`; batch judgment (contradictions, drift) with
+  `npx robrain synth`.
+- Perception re-redacts secrets server-side before anything is embedded or
+  stored, and RoBrain supports a fully-local mode (OpenAI-compatible local
+  server for extraction + embeddings) if you want zero external LLM calls.
+- Requires a reachable RoBrain deployment; there is no hosted default.
+
+## Running the tests
+
+The test suite (`../test_robrain_provider.py`) runs against a hermes-agent
+checkout, since it exercises the real `MemoryProvider` ABC:
+
+```bash
+git clone https://github.com/NousResearch/hermes-agent
+cp -r integrations/hermes/robrain hermes-agent/plugins/memory/robrain
+cp integrations/hermes/test_robrain_provider.py hermes-agent/tests/plugins/memory/
+cd hermes-agent && python -m pytest tests/plugins/memory/test_robrain_provider.py
+```
+
+(21 tests, no network — the HTTP client is stubbed. Verified end-to-end
+against a live RoBrain deployment on 2026-07-08: raw Hermes turn →
+server-side extraction → decision with structured veto → recall through
+both prefetch and the robrain_search tool.)