rarf GitHub avatar

optmem-hermes-plugin

rarf

OptMem is an independent, zero-dependency reimplementation of Victor Taelin's OptMem design, packaged as a Hermes Agent memory provider that offers cheap, always-on local memory with BM25 search, accent normalization, and native Windows support.

Stars

5

7-day growth

No data

Forks

0

Open issues

0

License

MIT

Last updated

2026-07-27

AI repository intelligence
FR-AI / ANALYSIS

Why it is worth attention

It provides a free, local, and permanent memory layer for AI agents — no network, no token cost — while being byte-compatible with the upstream design and adding ranked search, accent normalization, and native Windows locking that the original lacks.

Who it is for

  • Hermes Agent users who want a local fallback memory
  • AI developers building agentic systems with persistent memory
  • Developers on Windows seeking a working local memory solution
  • Privacy-conscious users who want data to stay on their machine

Use cases

  • Storing permanent, searchable memory for an AI agent without relying on cloud services
  • Providing offline-capable recall for AI assistants even without internet
  • Complementing cloud memory providers with a cheap, always-available local store
  • Using as a standalone memory store for Hermes Agent with automatic tool exposure

Strengths

  • Zero dependencies — pure Python standard library, no external SDKs
  • Sub-millisecond local BM25 recall, zero token cost per call
  • Accent-normalized BM25 search (e.g., 'cacula' finds 'caçula')
  • Fully tested with 18 end-to-end tests covering real engine and provider

Considerations

  • Hermes supports only one external memory provider at a time, so OptMem must be the sole provider or complemented by a cloud one (not both simultaneously)
  • Append-only design means memory never shrinks; old data is compressed via 'nap' but never deleted
  • Fixed-width record format (320/288 bytes) may be limiting for very long or diverse memory entries

README quick start

OptMem — local memory provider for Hermes Agent

A portable, dependency-free independent reimplementation of Victor Taelin's OptMem design, wired into Hermes Agent as a standalone MemoryProvider.

License note. The upstream VictorTaelin/OptMem repo currently ships without an explicit license (all rights reserved by default). This repository is an independent reimplementation of the published design and memory format — it does not copy the upstream source. It is released here under MIT (see LICENSE). If/once upstream adopts a license, this plugin will align with it.

  • Append-only LOG.txt + decay TREE/ — uses the same on-disk format as the original memo tool (fixed-width 320/288-byte records, identical cover/decay math), so logs produced here are byte-compatible and interchangeable with Taelin's implementation.
  • Accent-normalized BM25 recallrecall("cacula") finds the caçula memory.
  • Zero dependencies — pure Python standard library.
  • Native Windows — uses msvcrt advisory locks (with spin/backoff), no WSL.
  • Cheap, always-on — local BM25, no network round-trip, no per-call LLM cost.

Published as a standalone plugin repo per Hermes CONTRIBUTING.md: third-party memory providers no longer land under plugins/memory/ in the core tree. Install via ~/.hermes/plugins/ or pip.


Why OptMem

Hermes ships cloud-backed memory providers (Honcho, Mem0, Hindsight). They are powerful for cross-session user modeling, but they impose a network round-trip and — on reasoning tiers — an LLM call on every recall.

OptMem is the cheap, always-available local layer: permanent, searchable memory that survives restarts, costs zero tokens, and never leaves your machine. Hermes allows one external provider at a time, so the two are complementary — OptMem is the durable default; a cloud provider is selected when richer modeling is wanted.

DimensionOptMem (local)Cloud providers (e.g. Honcho)
Startup dependencyNone — is_available() is always TrueNeeds API key / base URL
Per-call latencyLocal BM25 (sub-ms to ms)Network, sometimes an LLM
Per-call co

Description

OptMem memory provider plugin for Hermes Agent (append-only, decay-compressed, BM25 search)

Related repositories

Similar projects matched by category, topics, and programming language.

lopopolo
Featured
lopopolo GitHub avatar

harness-engineering

Harness Engineering is a methodology for improving coding agent outputs by carefully crafting the environment around them—providing curated context, tools, and executable constraints that encode an organization’s nonfunctional requirements and cumulative lessons.

AI & Machine LearningAI Agents
2,390
slvDev
Featured
slvDev GitHub avatar

esp32-ai

A 28.9 million parameter language model runs on an $8 ESP32-S3 microcontroller entirely on-device, generating simple stories at about 9.5 tokens per second.

AI & Machine LearningLarge Language Models
1,960
littledivy
Featured
littledivy GitHub avatar

mimic

mimic captures traffic from any iOS or web app and automatically generates a Python client library that lets you call the app's API like a regular library.

AI & Machine Learning
1,482