Quickstart

Your first session with Sibyl Memory Plugin. By the end of this page you'll have written things to memory, recalled them by name, searched across everything you've stored, and confirmed it all survives between runs.

Before you start

You should have already followed the install guide. If you can run pip show sibyl-memory-hermes and see version 0.1.0 or newer, you're good.

Open a Python REPL

All the examples below work in a regular Python interactive prompt. Open one with:

python3

Step 1 · Connect to your memory

First, open your local memory database. This either creates a fresh one (first run) or opens the one you already have (every run after).

from sibyl_memory_client import MemoryClient

memory = MemoryClient.local("~/.sibyl-memory/memory.db")

That's it. No connection string, no API key, no auth. The memory lives on your disk; you're the only one who needs to ask for it.

Step 2 · Remember a fact

Sibyl Memory Plugin stores facts as entities. An entity has a kind (like "project" or "person"), a name, and a body of details. Here's how to remember that you have a project called Atlas:

memory.set_entity(
    "project", "atlas",
    {"status": "active", "owner": "jane", "stage": "staging"},
)

Step 3 · Recall it

Ask for the entity back by its kind and name:

result = memory.get_entity("project", "atlas")
print(result)

You'll see something like:

{
  'id': 'abc123…',
  'tenant_id': '00000000-…',
  'category': 'project',
  'name': 'atlas',
  'body': {'status': 'active', 'owner': 'jane', 'stage': 'staging'},
  'created_at': '2026-05-15T18:42:00.123Z',
  'updated_at': '2026-05-15T18:42:00.123Z',
}

Step 4 · Update it

The same call updates the entity if it already exists. Sibyl Memory Plugin keeps one canonical record per (kind, name) so the agent always has the latest version, not a pile of duplicates.

memory.set_entity(
    "project", "atlas",
    {"status": "shipped", "owner": "jane", "stage": "production"},
)

Step 5 · Record what happened

Facts are one kind of memory. Events. What actually happened today, in order. Are another. Use write_event to log them:

memory.write_event(
    evaluated={"question": "are we ready to deploy?"},
    acted=["reviewed atlas test suite", "deployed atlas v1.2"],
)

Read recent events back in time order:

for event in memory.read_events(limit=10):
    print(event["ts"], event["acted"])

Step 6 · Search across everything

Type a phrase, find every entity that mentions it:

results = memory.search_entities("atlas")
for r in results:
    print(r["category"], r["name"], r["body"])

Search runs locally and is fast even with thousands of entries. It matches names, kinds, and the full body of each entity.

Step 7 · Quit and come back

Close Python. Open it again. Re-run step 1 to connect. Then ask for Atlas:

memory = MemoryClient.local("~/.sibyl-memory/memory.db")
print(memory.get_entity("project", "atlas"))

Atlas is still there. So is everything else you wrote. Memory persists between sessions because it's a real file on your computer. Not a process you have to keep running.

What you just learned

• Facts live in set_entity / get_entity / search_entities. Updated in place.
• Events live in write_event / read_events. Append-only history.
• Memory persists between runs because it's a file on your disk.
• Everything you did happened on your machine. No cloud round-trips.

What's next

• There are three more kinds of memory beyond facts and events. How memory works walks through all five.
• If you're using Hermes, the SibylMemoryProvider handles all of this automatically. Your agent's conversations land in the right place without you calling these functions by hand. Hermes integration page (coming soon).
• Curious what the paid tier adds? Self-learning shows you the headline feature: your agent watching how you work and proposing reusable skills.