Built on Sibyl Memory, under it.

Sibyl decides what the agent remembers; kint decides where that memory lives and who can read it. This page names every seam between the two, and what breaks if you take Sibyl away.

Two jobs, two owners#

kint never changes how Sibyl ranks, gates or stores a row. Rows enter Sibyl's store through Sibyl's own write methods, whether the agent wrote them, a restore replayed them, or memory_verify wrote a refusal. kint's direct reads of the SQLite file open it read-only (mode=ro). The one time kint touches the file itself is kint pull --discard-local (or memory_pull with discard_local), which moves memory.db, memory.db-wal and memory.db-shm aside to a .kint-backup-<YYYYmmdd-HHMMSS> name before it restores. Nothing is deleted.

kint-server is their server plus six tools#

from sibyl_memory_mcp.server import build_server

def build_kint_server():
    mcp = build_server()   # their eight tools, exactly as shipped
    ...
    @mcp.tool()
    def memory_status() -> dict[str, Any]:
        ...

build_kint_server() calls Sibyl's build_server(), which returns their FastMCP server with their eight tools registered, then adds six @mcp.tool() functions to the same object. No line of Sibyl is edited and none of their functions is replaced. kint puts one thing into their module, the client described below, and wraps five write methods on that one client object so it can tell a write through the tools from an edit made behind them (The writes kint watches).

tests/test_mcp_stdio.py starts python -m kint.server over real stdio, asserts that all fourteen names are listed, and calls Sibyl's memory_remember and memory_search, then five of kint's tools, through it. The full parameter list for every tool is in MCP tools.

kint setup registers kint-server with Claude Code, Codex, Hermes and OpenClaw and leaves any sibyl-memory-mcp registration alone. For Claude Code it prints a reminder to run claude mcp remove -s user sibyl-memory if Sibyl's own server is also registered (one store, one server). A second server over the same store would build its own client, so its copy of the eight tools would not count kint's bytes against the cap, and its writes would look to kint like edits made behind the tools.

One client, one cap#

store.open_client() builds the MemoryClient "exactly the way Sibyl's server does, plus the volunteered cap". It reads the same credentials (Sibyl's _load_credentials()), takes the tier from them (default free), and keeps Sibyl's tier_cache.json beside the store. The store is SIBYL_MEMORY_DB, or ~/.sibyl-memory/memory.db when that is unset. The tenant is KINT_TENANT, then the credentials' tenant_id, then their account_id, then Sibyl's DEFAULT_TENANT.

store.seed_sibyl_server_cache() then writes that client into Sibyl's module-level _client_cache, under Sibyl's own _client_lock, together with the current credentials.json mtime and whether the file exists. Sibyl's _open_client() rebuilds its client only when there is none, or when that mtime or existence changed, so their eight tools find kint's client and use it.

If credentials.json changes while the server runs (Sibyl's trigger for sibyl upgrade), Sibyl rebuilds its own client, with a gate that counts only Sibyl's stores, and their tools use it until a kint-server pull that finds new epochs builds kint's client again and reseeds the cache, or until a restart. kint's own tools keep kint's client. The rebuilt client is not one kint watches, so while their tools use it, a write through them to a row that is already anchored reads as a change made behind them, and kint-server holds its own pushes until you run kint push from a terminal or restart the server. More on the client in How it works.

The cap is volunteered through the size function Sibyl's gate calls. MemoryClient takes a cap_gate, and CapGate takes a db_size_fn:

def volunteered_size_fn(db_path: Path):
    def fn() -> int:
        return aggregate_db_size(db_path) + paths.footprint_bytes()
    return fn

gate = CapGate(..., db_size_fn=volunteered_size_fn(db_path), local_tier_hint=tier, ...)
MemoryClient(storage, ..., cap_gate=gate, ...)

aggregate_db_size is Sibyl's own count across every store it resolves on the machine; footprint_bytes() is every file under KINT_HOME (default ~/.kint). Before each write, Sibyl's gate checks that size plus the size of the proposed write. The cap (FREE_TIER_CAP_BYTES, 5 MiB), the tier decision and the refusal stay Sibyl's; kint changes only what the size counts. A write that would take the sum past the cap meets Sibyl's gate the way Sibyl's own overflow would, and that includes rows a pull replays. Inside the write transaction Sibyl re-checks the store's own absolute size, which leaves kint's bytes out unless that measurement fails and the gate falls back to the size function. The size function can run under Sibyl's BEGIN IMMEDIATE write lock (archive_entity checks the cap inside its transaction, and so does that fallback), which is why kint's half is a local file walk: nothing in store.py touches the chain, an RPC or a signer.

The last four lines of kint status:

cap accounting (the same 5 MiB free cap Sibyl enforces):
  sibyl stores      <size>
  kint state        <size>   (mirror, epoch cache, keys; volunteered)
  enforced total    <size> of 5.00 MB

Sizes print in KB with one decimal below 1 MiB, and in MB with two decimals from 1 MiB up. memory_status returns the same numbers as cap: sibyl_bytes, kint_bytes, volunteered_total, cap_bytes and db_path.

On an activated free-tier account, Sibyl's own sibyl status reports one store's WAL-inclusive size as a share of the free cap, and lists every store it resolves when there is more than one. It knows nothing about ~/.kint, so its percentage leaves kint's bytes out. The number the gate checks before writes made through kint's client is the enforced total line. KINT_HOME is outside every store aggregate_db_size sizes, so kint's bytes enter the count once, through the size function, and kint doctor fails its kint home placement check when KINT_HOME is inside ~/.sibyl-memory (why).

The writes kint watches#

On the one client, kint-server wraps five write methods: set_entity, set_state, set_reference, archive_entity and delete_entity. Each wrapper calls Sibyl's method first, unchanged, and returns its result. Only after it returns does kint re-read that one row read-only and note its leaf as the value the tool path wrote; a failure in that bookkeeping never reaches the caller. Their eight tools, kint's own tools and a pull's replay all write through this client.

Those notes are what let kint tell a write through the tools from an edit made behind them. The watcher, the exit hook and memory_push check them before anchoring. A row whose stored text differs from the leaf this machine last saw anchored holds the push when either:

• it changed, or vanished, while the server was running, with no write through the tools to account for it (edited straight in SQLite, say); or
• a kint_refusal entity names exactly the value it holds now.

A held push returns error HELD with nothing anchored and nothing dropped, memory_status carries the message under held, and the watcher waits for the store to change again instead of retrying. The notes reset to the store's current leaves at start and after every successful pull and push, so a row changed before the server started is not held on that ground alone. write_event is not wrapped: a journal event has no key to overwrite, so an edited one shows up as a new row plus a vanished anchored one, and the vanished one holds the push. kint push from a terminal never runs this check.

What kint relies on inside Sibyl#

kint uses a short, fixed list of Sibyl's code. Everything else in Sibyl is theirs to change.

Note. MemoryClient, Storage, DEFAULT_TENANT, CapGate, TierCache, FREE_TIER_CAP_BYTES, VerdictCode and explain are exported by sibyl_memory_client itself (kint imports the cap names from _capcheck, where they are defined). The rest is not published as API: the server's _client_cache, _client_lock, _credentials_mtime(), _load_credentials() and DEFAULT_CRED_PATH, aggregate_db_size, multi_record_search (not in the package's __all__; kint imports it from sibyl_memory_client.multi_record, where Sibyl's own memory_search imports it from), and the table and column names the export reads. That is why kint pins sibyl-memory-client>=0.8.1,<0.9 and sibyl-memory-mcp>=0.2.1,<0.3: an install of kint never resolves a Sibyl release outside those ranges.

Search and the typed verdict#

memory_verify calls multi_record_search(client, query, limit=limit) (limit defaults to 5) on the same client that serves Sibyl's tools. It is the call Sibyl's memory_search makes when it is given no tiers: a two-stage search that retrieves candidates with client.search (Sibyl's cross-tier FTS5 search over entities_fts, state_documents_fts, reference_documents_fts and journal_events_fts, with the folded-trigram shadow table as a fallback), then drops the ones Sibyl's precision gates reject. It returns a SearchResults: a list of hits in the shape client.search returns, with one typed verdict attached.

Six verdict codes are reachable. ok comes with hits; the other five name why a result is empty:

kint keys on the code: anything but ok, or zero hits, refuses with no ranked candidate to act on: Sibyl's verdict is <code>. Sibyl's memory_search given tiers calls client.search directly and skips those gates, so a tier-filtered search can return a row that memory_verify then refuses. The rest of the decision is in Verify before acting.

After the verdict, verify checks the chain head when its caller could read it. memory_verify reads the head outside every Sibyl write and passes it in; kint verify does the same unless KINT_OFFLINE=1. A head that differs from this machine's mirror refuses with chain moved to seq N at block B, pull first, because another machine may have superseded the row. When the head cannot be read, verify checks against the local mirror only and says so, in kint.log for the tool and on stderr for the CLI.

A refusal over a drifted row goes back into Sibyl as an entity: client.set_entity("kint_refusal", name, {...}, status="refused"), with the name <tier>-<category or none>-<key>-<unix seconds> cut to 200 characters. A fresh session finds it through Sibyl's own tools, and kint-server reads it back: while the row still holds the value a refusal named, every push the server makes itself is held.

The four write methods#

A restore replays rows through the SDK, never through SQL (restore.py):

def write_row(client, row: Row) -> None:
    if row.tier == "entity":
        client.set_entity(row.category, row.key, loads(row.body), status=row.status)
    elif row.tier == "state":
        client.set_state(row.key, loads(row.body))
    elif row.tier == "reference":
        client.set_reference(row.key, row.body if row.body is not None else "",
                             metadata=loads(row.meta) if row.meta is not None else None)
    elif row.tier == "journal":
        client.write_event(
            evaluated=loads(row.evaluated), acted=loads(row.acted),
            forward=loads(row.forward), extra=loads(row.extra), ts=row.ts,
        )

Deletions replay first, then rows in the order the export read them (rowid order on the machine that pushed). Only entities have an SDK delete, so a deletion replays as delete_entity and any other tier is reported as no SDK delete for this tier. After the replay every row is exported again and its leaf compared with the anchored one; a row that differs is reported as stored text differs from the anchored leaf after replay, and one that did not come back as row missing after replay. Pull records either as a warning on that epoch, never as a silent success. When the epoch is a snapshot, only rows whose stored text differs are replayed, because writing a journal event again would duplicate it (an event has no key to overwrite).

Going through the SDK is what makes the restored store answerable: Sibyl's indexes, its shadow table and its cap gate see a replayed row the way they see any write. The row ids (uuids) and the entity, state and reference timestamps regenerate on replay. The journal ts survives, because write_event takes it as an argument.

The exact stored TEXT#

Sibyl's storage.dumps() turns every JSON value the SDK stores into TEXT (entity and state bodies, journal payloads, reference metadata, and a reference body passed as a dict or list) with json.dumps(payload, separators=(",", ":"), ensure_ascii=False). It does not sort keys; its docstring says sort_keys=False, to preserve insertion order. A reference body passed as a string is stored as given. kint's leaf hashes the stored TEXT column exactly as it sits in SQLite, read by SQL and never re-serialised. In canon.py's words, re-serialising "would refuse every row on device two".

On replay, loads() hands the SDK a value with its keys in stored order, and dumps() writes it back as the same TEXT (a reference body goes back as the stored string itself), so the leaf a new machine computes is the leaf the chain anchored. The leaf leaves out the timestamps Sibyl regenerates (entity, state and reference updated_at) and includes the journal ts. Leaves are ordered by their canonical key, never by rowid, so every machine computes the same root over the same content.

What the export covers#

export.py reads the four tiers the SDK writes, for one tenant, by raw SQL in rowid order, over a read-only connection. The SDK has no enumeration for state or reference documents and no rowid ordering anywhere (list_entities orders by updated_at DESC and clamps), so the export reads the tables directly. The restore is the half that goes through the SDK.

read_row() re-reads one row by the key Sibyl's search returned: an entity by tenant, category and name, a state or reference document by its key, a journal event by its Sibyl event id (and recomputes the same ordinal the export assigns). That is the text memory_verify hashes.

What it does not cover#

• Other tables. entity_relations, revenue_events, error_events, archived_entities, flagged_actors, skill_proposals and learning_runs are not exported.
• The archive. memory_forget moves an entity from entities into archived_entities with its reason. kint sees the entity leave entities and anchors a deletion, so the anchored state is right, but the archived copy is not carried: a restore replays the forget as a plain delete, and the restored machine has the entity gone and no archive row.
• Derived indexes. The FTS5 indexes and the shadow table are not exported. Sibyl's own insert triggers fill them as the replay writes rows.
• Other tenants. Every query filters on the one tenant kint serves.
• Row ids and write timestamps. They regenerate on replay, as above.
• Account files. credentials.json and tier_cache.json are not rows and are not exported.

Delete the Sibyl Memory layer and what breaks#

In the README's words:

The decision beat reaches the row through Sibyl's memory_search (four FTS5 indexes plus the shadow fallback) and keys on the typed verdict from verdicts.py. Without Sibyl there is no ranked candidate and no verdict to key on: the epoch is a decrypted blob with no query surface, so a fresh session neither refuses nor proceeds. Base holds the ciphertext; Sibyl is what turns it back into an answerable store. See docs/judge.md for the claims table with file and line.

Precisely, kint calls multi_record_search, the call memory_search makes, on the same client. Taken one call at a time:

• Remove the multi_record_search(...) call in src/kint/verify.py and there is no ranked candidate and no verdict: the decision cannot be made.
• Remove sibyl_memory_mcp.build_server() from src/kint/server.py and no harness can read or write memory at all.
• Remove the four SDK write calls in src/kint/restore.py and a restored machine has an encrypted blob and an empty store.

Prior work#

• Sibyl Sovereign (Sibyl Labs, in development): a cryptographic seal on every critical file, re-checked before every action, fail-closed, with an append-only audit trail. kint applies that mechanism one tier down, to the memory store itself, on Base. Same idea, theirs first.
• anima (s0nderlabs, 0G): anchors a keystore root hash on chain, roots only. On 0G the storage primitive is native; on Base a root alone is a receipt for data you still have to store somewhere, which is why kint puts the ciphertext itself in calldata.
• ERC-8350 (Agent Memory State Registry, draft): the vocabulary of a per-space linear chain of committed deltas describes kint's epochs exactly. Reference shape only, not implemented.
• The verify-a-local-artifact-against-an-anchor pattern exists in several hackathon entries. Restoring the memory itself from the chain, and showing a superseded belief, do not.

The claims table#

docs/judge.md pairs kint's claims with the file and line that implement them, against Sibyl Memory at revision 761bfc6 (client 0.8.1, mcp 0.2.1), and lists what is not built. pytest -q and forge test run the tests that pin the claims; tests/test_audit_fixes.py pins the hold, the verdict and chain-head refusals, and the pull past an epoch that never opens. scripts/gen_judge.py regenerates the table by searching each file for the line that implements each claim.

Read Limits and threat model next.

Source: src/kint/server.py, src/kint/store.py, src/kint/export.py, src/kint/restore.py, src/kint/verify.py, src/kint/canon.py, src/kint/paths.py, tests/test_audit_fixes.py, README.md, docs/judge.md, and Sibyl's sibyl_memory_mcp/server.py, sibyl_memory_client/_capcheck.py, client.py, multi_record.py, schema.sql, shadow.py, storage.py and verdicts.py in Sibyl-Memory.