sibyl-memory-hermes

Sibyl Memory SDK + bundled Hermes plugin payload. Local-first, SQLite-backed, structured-tier memory for Hermes v0.13+ (and any Python orchestration that wants direct SDK access).

The package ships two things:

1. SibylMemoryProvider: a framework-agnostic SDK class. Call it directly from any Python code that wants structured local memory.
2. A bundled Hermes plugin payload: a thin adapter implementing Hermes v0.13's MemoryProvider ABC. Installed into $HERMES_HOME/plugins/sibyl/ by the sibyl-memory-hermes install-plugin console script.

Memory content lives on the user's own machine, never on our servers. Built on sibyl-memory-client, the SDK foundation.

Install (Hermes path)

Hermes' loader uses filesystem discovery, NOT pip entry points. A pip install alone won't make Sibyl visible to Hermes: the install-plugin console script bridges the gap.

pip install sibyl-memory-hermes
sibyl-memory-hermes install-plugin

Sibyl Memory runs on Linux, macOS (Apple Silicon and Intel), and Windows through WSL2. Native Windows is not supported.

Then edit ~/.hermes/config.yaml:

memory:
  provider: sibyl

Restart Hermes. Four tools become available to the agent:

• sibyl_remember(category, name, body): store a structured fact
• sibyl_recall(category, name): look up a known fact
• sibyl_search(query). FTS5 search across all four tiers (entities, state, journal, reference); hits are tier-tagged
• sibyl_list(category?, status?): browse what's remembered

Optional: lift the 5 MB free-tier cap by binding your account:

pip install sibyl-memory-cli
sibyl init

Direct SDK use (any Python orchestration)

from sibyl_memory_hermes import SibylMemoryProvider

provider = SibylMemoryProvider()         # auto-loads ~/.sibyl-memory/credentials.json
provider.remember("project", "atlas", {"status": "shipping v2 friday"})
provider.recall("project", "atlas")      # → {id, tenant_id, category, name, body, ...}
provider.set_state("active_branch", {"name": "v0.3.1"})
provider.save_context(
    inputs={"user": "what changed in v0.3.1?"},
    outputs={"assistant": "..."},
)
provider.search("v0.3.1")                # FTS5 across entities + state + reference + journal

Environment overrides

Precedence: explicit SIBYL_TENANT_ID > credentials.json (tenant_id then account_id) > the shared default tenant. Set it when one machine or container needs to target a specific tenant without editing the credential file.

Why "local-first"?

Mem0, Zep, Honcho, and most other agent-memory products centralize user context on their servers. The Sibyl Memory Plugin keeps the data on the user's disk. Our cloud schema has no memory-content tables. Even with admin DB access we cannot read what users have written. That's the difference between "we promise we don't" and "we structurally can't."

Architecture: five tiers, not one bucket

The provider routes operations onto the appropriate memory tier instead of dumping everything into a single vector store:

Different intents, different lookups, no embedding model required. FTS5 covers full-text search out of the box.

Hermes contract

The Hermes plugin is implemented by a bundled adapter at _hermes_plugin/adapter.py. The adapter is copied into $HERMES_HOME/plugins/sibyl/ by the install-plugin console script and is what Hermes' filesystem loader picks up. The adapter implements Hermes v0.13's MemoryProvider ABC and delegates every call to SibylMemoryProvider. Verified against hermes-agent through 0.19.0 (current): the adapter loads via the live ABC and instantiates cleanly.

The SDK class itself (SibylMemoryProvider) is framework-agnostic: it does not inherit from any framework ABC. This is the v0.3.0 architecture shift. v0.2.x and earlier attempted soft-inheritance via a broken import path; that path was removed and the adapter pattern replaced it.

Activation

Most users get here via the sibyl init CLI (from sibyl-memory-cli), which writes ~/.sibyl-memory/credentials.json after browser authentication. The provider auto-detects this file on construction.

For pre-activation use (tests, internal tooling):

from sibyl_memory_hermes import SibylMemoryProvider

provider = SibylMemoryProvider(
    db_path="/tmp/test-memory.db",
    tenant_id="test-user",
    autoload_credentials=False,
)

Free tier

• 5 MB local soft cap (with server-authoritative tier verification at the cap boundary)
• Single device
• All five tiers (HOT/WARM/COLD/REFERENCE/ARCHIVE)
• FTS5 full-text search across entities + state + reference + journal
• Multi-tenant isolation
• Per-profile memory isolation: each Hermes profile gets its own DB automatically (<HERMES_HOME>/sibyl/profiles/<name>/memory.db), so specialist agents don't share or leak memory

Paid tiers (Stake, Sync, Lifetime, Enterprise) unlock self-learning, the memory check-up, no cap, and (in build) cross-device encrypted sync. See docs.sibyllabs.org/memory/tiers.

Documentation

• Full docs: docs.sibyllabs.org/memory/
• Hermes integration guide: docs.sibyllabs.org/memory/integrations#hermes
• Install guide: docs.sibyllabs.org/memory/install

License

MIT. Package on PyPI: pypi.org/project/sibyl-memory-hermes.

Citation

The Sibyl Memory Plugin holds #2 globally on the LongMemEval Oracle benchmark. The benchmark methodology and report are at blog.sibylcap.com/longmemeval-v2.