Cortext for Hermes

Your Hermes agent forgets everything the moment a session ends. Install the production Cortext package, then enable this plugin — permanently, locally, invisibly.

# 1. Production Cortext package (natives + model assets; see Install below)
curl -fsSL -o /tmp/cortext-index.html \
  https://github.com/augmem/cortext.py/releases/download/v1.2.4/index.html
pip install 'cortext==1.2.4' --find-links file:///tmp/cortext-index.html

# 2. Hermes plugin
hermes plugins install augmem/cortext-hermes-plugin --enable
hermes config set memory.provider cortext

augmem/cortext-hermes-plugin gives Hermes Agent durable memory backed by Cortext, a local neuromorphic memory engine. Everything your agent learns lands in a SQLite file on your machine. Nothing is sent to a memory API. No LLM summarizes your conversations. And the model never sees a memory tool — recalled facts simply arrive as prior context, as if the agent just… remembered.

What changes

Tell Hermes something once. Close the session. Days later, in a brand-new session, it still knows.

── Monday ────────────────────────────────────────────────
you    › We deploy from the `release` branch, never `main`.
         Staging is at 10.0.4.7 and the on-call runbook is in ops/RUNBOOK.md.
hermes › Got it.
         (session ends — nothing pinned, no notes file, no tool calls)

── Friday, fresh session ─────────────────────────────────
you    › Ship the fix.
hermes › Cutting the release from `release` — you deploy from there,
         not `main`. I'll verify against staging at 10.0.4.7 first.

This is what that unlocks in practice:

• A coding agent that knows your project. Conventions, gotchas, "we tried that and it broke prod" — retained across sessions without you re-explaining or maintaining a notes file.
• A personal assistant that actually knows you. Allergies, appointments, preferences, the names that matter. Because memory is a local file, this is finally private enough for the personal stuff.
• An ops agent with institutional memory. Which host is flaky, what the last incident looked like, which dashboard is the real one.
• Corrections that stick. Cortext supersedes stale facts instead of hoarding contradictions — tell it the appointment moved, and the old time stops being recalled.
• Compaction that doesn't lobotomize. The plugin ships a full Hermes context engine: compaction becomes a 20-millisecond local memory operation instead of an auxiliary-LLM summarization call. Nothing is irreversibly lost — every turn is already in the durable store — and it keeps working when cloud LLMs are down (which is exactly when the built-in summarizer silently drops your history).

Memory management is automatic. There is no "save this" command, no memory tool for the model to call (or forget to call), and no LLM in the loop deciding what to keep. Cortext's write gate, decay, and consolidation decide — deterministically, on your machine.

Benchmarked against the providers people actually use

Same scripted 4-session transcript through every provider's real Hermes seams, cold-start probes, blind LLM judging. Full method, caveats, and reproduction steps in bench/README.md; raw packets and verdicts in bench/results/.

	cortext	mem0 (most popular, 60.5K★)	tencentdb (Tencent Cloud)	holographic (built-in default)
Facts recalled (packet)	10/14	8/14	4/14	0/14
Superseded facts leaked	0	1	1	0
Effective tokens per turn	194	435	1,387	632
Median recall latency	15 ms	459 ms	169 ms	—
Blind-judge answer score	56	35	36	26 (= no memory at all)
Works offline	yes	no	no (LLM extraction)	yes
LLM calls to maintain memory	0	every write	every write	0
Model-visible tools	0	3	2	2

Compaction ablation

When context fills up, Hermes's built-in compactor summarizes history with an auxiliary LLM. The Cortext context engine replaces that with a local memory operation. Forced compaction of a 6,638-token transcript, then fact probes against the compacted context:

	Facts kept	Compaction time	LLM calls
No compaction (upper bound)	14/14	—	—
Built-in summarizer	13/14	8.7 s	1
Built-in summarizer, aux LLM down	0/14	0.6 s	0
Cortext engine	11/14	0.02 s	0

The built-in keeps one more fact — when its cloud LLM chain is healthy. When it isn't, its shipped fallback silently drops your history. Cortext's compaction is ~400× faster, free, offline, and has no failure mode that costs you your memory. Reproduce: python -m bench.compaction_ablation.

Cold-start recall, verified live

Not a demo script — a live control/treatment test against Hermes 0.15.2 with gpt-5.4-mini:

1. A first Hermes session stored a unique medical fact, then shut down.
2. A new control session, with memory disabled and no prior chat history, did not know the fact.
3. A second new session, with only Cortext's reopened SQLite database, recalled the secret identifier, treatment, and appointment details — without using the word "Cortext."

That is durable retrieval from disk, not conversation-history leakage.

Private by architecture, not by policy

• Memories live in one SQLite file (default: $HERMES_HOME/cortext.sqlite). Back it up, inspect it, delete it — it's yours.
• Zero network calls at runtime. No memory SaaS, no embedding API, no runtime downloads. The local AIST encoder and natives ship in the cortext==1.2.4 wheel (checksum-verified by the package) — not in this Git plugin alone.
• Works fully offline after the production package and this plugin are installed; a clean Git-only plugin install is not enough without cortext.

Invisible to the model

This provider is intentionally silent:

• no cortext_* tools for the model;
• no system-prompt branding;
• recalled facts arrive as plain prior context.

Text, WAV audio, and non-interlaced 8-bit PNG images work with no Python dependencies. Other image containers are skipped rather than silently adding or downloading a decoder.

Install

1. Install the production Cortext package

Wheels ship platform natives + model assets from GitHub Releases (not PyPI):

curl -fsSL -o /tmp/cortext-index.html \
  https://github.com/augmem/cortext.py/releases/download/v1.2.4/index.html
pip install 'cortext==1.2.4' --find-links file:///tmp/cortext-index.html

Windows (PowerShell):

$index = Join-Path $env:TEMP "cortext-index.html"
Invoke-WebRequest -Uri "https://github.com/augmem/cortext.py/releases/download/v1.2.4/index.html" -OutFile $index
$uri = ([Uri]$index).AbsoluteUri
pip install "cortext==1.2.4" --find-links $uri

Or (Unix):

curl -fsSL https://github.com/augmem/cortext.py/releases/download/v1.2.4/install.sh | bash -s -- v1.2.4

This matches the production packaging bar used by:

Host	Production package
OpenClaw	@augmem/cortext (^1.2.3)
CPA	github.com/augmem/cortext.go (v1.2.4)
Hermes	cortext Python package (v1.2.4)

2. Install the Hermes plugin

hermes plugins install augmem/cortext-hermes-plugin --enable
hermes config set memory.provider cortext

Even with --enable, Hermes still requires selecting Cortext as the memory provider (see after-install.md).

Configuration

Optional. Drop a cortext.json in your Hermes home ($HERMES_HOME/cortext.json) to tune behavior; every key has a sensible default:

{
  "db_path": "$HERMES_HOME/cortext.sqlite",
  "focus": 0.45,
  "sensitivity": 0.50,
  "stability": 0.50,
  "auto_consolidate": true,
  "ingest_media": true
}

focus, sensitivity, and stability are Cortext's three homeostatic control knobs — retrieval selectivity, responsiveness to surprising input, and preference for durable context. The engine decides how much to recall; everything it retrieves is injected as-is (working memory joins the packet only right after a context compaction, when it replaces the discarded recent context).

How it ships

This plugin is a thin Hermes adapter. The Cortext engine comes from the production Python package:

Piece	Source
Plugin hooks + provider	this repo (provider.py, cortext_context.py, media.py)
Native engine + model assets	cortext==1.2.4 wheel
Packaging standard	same as openclaw @augmem/cortext and CPA cortext.go

Install the wheel into the Python environment Hermes uses, then install this Git plugin.

Supported platforms

Platform	Architecture	Bundled library
macOS	Apple Silicon	libcortext.dylib
macOS	Intel	libcortext.dylib
Linux	x64	libcortext.so
Linux	arm64	libcortext.so
Windows	x64	cortext.dll

The exact version, target names, paths, and SHA-256 values are in Natives and model assets ship inside the production cortext wheel (cortext==1.2.4).

Under the hood

• provider.py implements Hermes MemoryProvider hooks and talks to cortext.Cortext.
• cortext_context.py optionally owns compaction by injecting a memory snapshot instead of an LLM summary.
• media.py normalizes text/audio/image payloads without third-party Python deps.
• Availability is cortext.package_assets_ready() from the installed production package.

Verify

curl -fsSL -o /tmp/cortext-index.html \
  https://github.com/augmem/cortext.py/releases/download/v1.2.4/index.html
pip install 'cortext==1.2.4' --find-links file:///tmp/cortext-index.html
python -c "import cortext; assert cortext.package_assets_ready(); print(cortext.version())"
PYTHONPATH=. python -m unittest discover -s tests -v

License

Apache-2.0. See LICENSE and NOTICE.