Metadata-Version: 2.4
Name: sibyl-memory-hermes
Version: 0.2.1
Summary: Hermes Agent memory provider for the Sibyl Memory Plugin family. Local-first, SQLite-backed, structured-tier memory for Hermes v0.10.0+.
Author-email: Sibyl Labs <sibyl@sibyllabs.org>
License: MIT
Project-URL: Homepage, https://sibyllabs.org/plugin
Project-URL: Documentation, https://docs.sibyllabs.org/memory/
Keywords: sibyl,memory,hermes,agent,sqlite,local-first,agentic-memory,agent-framework
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sibyl-memory-client>=0.3.1
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Provides-Extra: hermes
Requires-Dist: hermes-agent>=0.10.0; extra == "hermes"
Dynamic: license-file

# sibyl-memory-hermes

**Hermes Agent memory provider for the Sibyl Memory Plugin family. Local-first, SQLite-backed, structured-tier memory for Hermes v0.10.0+.**

Drop-in memory for [Hermes Agent](https://hermes-agent.dev) (and any other Python agent framework). Memory content lives on the user's own machine, never on our cloud. Built on [`sibyl-memory-client`](https://pypi.org/project/sibyl-memory-client/), the underlying SDK.

```bash
pip install sibyl-memory-hermes
```

## Quickstart

```python
from sibyl_memory_hermes import SibylMemoryProvider
from hermes_agent import Agent

# Default: reads ~/.sibyl-memory/credentials.json (written by `sibyl init`)
# and opens ~/.sibyl-memory/memory.db
agent = Agent(memory=SibylMemoryProvider())

# Per-turn memory (Hermes contract):
agent.run("What did I work on yesterday?")
# SibylMemoryProvider.save_context(inputs, outputs) lands in the journal

# Fact store:
agent.memory.remember(
    "project", "atlas",
    {"status": "active", "stage": "staging"}
)
agent.memory.recall("project", "atlas")

# Full-text search across all entities:
results = agent.memory.search("error budget")
```

## Why "local-first"?

Mem0, Zep, Honcho, and every other agent-memory product 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 in it. Even with admin database access we cannot read what users have written. That's the difference between *"we promise we don't"* and *"we structurally can't."*

| | Sibyl Memory Plugin | Typical hosted memory |
|---|---|---|
| Memory content lives | on user's disk | on vendor's servers |
| Query latency | local SQLite (sub-ms) | round-trip + vector search |
| Privacy claim | structurally enforced | policy-only |
| Free-tier cost to vendor | near-zero | scales with users |

## Architecture: five tiers, not one bucket

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

| Intent | Tier | Storage call |
|---|---|---|
| save the conversation turn | COLD journal | `save_context(inputs, outputs)` |
| remember a fact | WARM entity | `remember(category, name, body)` |
| current state | HOT state | `set_state(key, body)` |
| lookup a runbook | REFERENCE | `set_reference(key, body)` |
| archive stale entity | ARCHIVE | `archive(category, name)` |
| search by content | FTS5 | `search(query)` |

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

## Hermes contract

If Hermes v0.10.0+ is installed, `SibylMemoryProvider` inherits Hermes' `MemoryProvider` ABC at import time so framework-level `isinstance` checks pass. The contract methods:

- `save_context(inputs, outputs)` writes to the journal
- `load_context(limit)` reads recent turns
- `clear_context()` no-op (journal is append-only by design)

If Hermes isn't installed, the provider still works standalone. Any framework that calls these methods directly works.

## Activation

Most users get here via the `sibyl init` CLI (from the [`sibyl-labs-cli`](https://pypi.org/project/sibyl-labs-cli/) package), which writes `~/.sibyl-memory/credentials.json` after browser authentication. The provider auto-detects this file on construction.

For pre-activation use (e.g., in tests):

```python
from sibyl_memory_hermes import SibylMemoryProvider

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

## Free tier

- 2 MB local soft cap (gentle prompt, not a hard wall)
- Single device
- All five tiers (HOT/WARM/COLD/REFERENCE/ARCHIVE)
- FTS5 full-text search
- Multi-tenant isolation

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](https://docs.sibyllabs.org/memory/tiers).

## Documentation

Full docs: [docs.sibyllabs.org/memory/](https://docs.sibyllabs.org/memory/).
Install guide: [docs.sibyllabs.org/memory/install](https://docs.sibyllabs.org/memory/install).

## License

MIT. Package on PyPI: [pypi.org/project/sibyl-memory-hermes](https://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](https://blog.sibylcap.com/longmemeval-v2).
