Metadata-Version: 2.4
Name: hermes-persql
Version: 0.1.0
Summary: Hermes Agent memory provider backed by PerSQL — portable agent memory in an isolated SQLite database per agent, with FTS5 recall.
Project-URL: Homepage, https://persql.com
Project-URL: Documentation, https://docs.persql.com
Project-URL: Console, https://console.persql.com
Project-URL: Issues, https://persql.com/support
Author-email: PerSQL <support@persql.com>
License: MIT
License-File: LICENSE
Keywords: agent,hermes,memory,nous,persistence,provider,sqlite
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: persql>=0.4
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest>=7; extra == 'test'
Description-Content-Type: text/markdown

# hermes-persql

A [Hermes Agent](https://hermes-agent.nousresearch.com) memory provider
backed by [PerSQL](https://persql.com).

Hermes keeps its sessions and memory in a local `~/.hermes/state.db`.
This provider routes them into a **PerSQL database** instead — one
isolated SQLite per agent, on the edge — so your agent's memory is
**portable**: query it in SQL, sync it across machines, share it across
agents. Recall is FTS5, mirroring Hermes's own lexical session search.

## Install

```bash
pip install hermes-persql
hermes-persql install            # writes ~/.hermes/plugins/persql/
```

`hermes-persql install` drops the small directory plugin Hermes
discovers (under `$HERMES_HOME/plugins/`). Then point Hermes at it:

1. Set the provider in `~/.hermes/config.yaml`:

   ```yaml
   memory:
     provider: persql
   ```

   (or run `hermes memory setup` and pick PerSQL).

2. Provide credentials:

   ```bash
   export PERSQL_TOKEN="psql_live_…"        # console.persql.com -> API tokens
   export PERSQL_DATABASE="<workspace>/<slug>"
   ```

   Or store them with `hermes memory setup`, which writes
   `~/.hermes/persql.json`.

That's it — Hermes calls the provider on each turn.

## What it stores

| Hermes hook | PerSQL |
|---|---|
| `sync_turn` | appends the turn to `hermes_turns` (+ FTS index) |
| `prefetch` | FTS5 recall of relevant turns/facts, injected before the next call |
| `persql_remember` tool | stores a durable fact in `hermes_facts` |
| `persql_recall` tool | searches turns and facts by relevance |
| `persql_profile` tool | lists all stored facts |

Writes run on Hermes's own background sync worker (which it drains at
session end), so the agent loop is never blocked on the network and the
last turn isn't lost when a short `hermes -z` process exits.

## Requirements

- Python 3.10+
- A running Hermes Agent (provides the `MemoryProvider` interface)
- A PerSQL token and database — sign up at
  [console.persql.com](https://console.persql.com)

## License

MIT
