Their eight tools ship unmodified; kint adds six.

kint-server is one MCP server on stdio: Sibyl's own build_server() registers their eight memory_* tools exactly as shipped, and kint registers six more on the same instance.

What the server does around the tools#

A harness sees fourteen tools. This page lists every one: its parameters and defaults, what it returns, and every error it can return.

• One client. kint opens one MemoryClient on the store at SIBYL_MEMORY_DB (default ~/.sibyl-memory/memory.db) for the tenant in KINT_TENANT (else Sibyl's credentials.json, else Sibyl's default), and seeds it into Sibyl's module cache. Their eight tools write through it, so KINT_TENANT picks their tenant too, and the cap they enforce counts kint's own footprint against Sibyl's 5 MiB free-tier cap (5,242,880 bytes). If Sibyl's credentials.json changes while the server runs, Sibyl's cache builds its own client again; restart kint-server after that.
• Pull on start. When this machine is connected and the data key is cached, the server pulls from Base as it starts. It waits for that pull at most KINT_BOOTSTRAP_SECONDS, then serves while the pull finishes behind it; a memory_pull or memory_push in the meantime waits for the pull's head lock, up to 30 seconds. A fork, a freshness refusal or a failed pull is logged, and the server serves the local store anyway. Harnesses has the timeouts.
• Push while serving. A watcher polls the store's modification time and pushes unanchored changes after a quiet period, or sooner when the change set grows past a size estimate. It pushes only when the machine is connected and the data key is cached, and it starts with whatever rows an earlier session left unanchored.
• Hold instead of launder. Every push the server makes (the watcher's, the exit push, memory_push) checks the store first and answers HELD, anchoring nothing, when a row the chain vouches for changed behind Sibyl's tools while the server ran, or when memory_verify already refused exactly the value it holds. kint push in a terminal is never held. Limits has the edges.
• Renew the data key. Every successful pull and push moves the cached data key's deadline forward by KINT_KEY_TTL, so a server in use does not lapse.
• Push on exit. On a normal exit, SIGTERM or SIGHUP, the server pushes whatever is unanchored, once and best effort. The signal handler only marks the exit; the push runs after the tool call in flight has finished, never inside a Sibyl write.
• Logs never touch stdout. The stdio transport owns stdout. kint logs to stderr and to kint.log under KINT_HOME (default ~/.kint).

The rest of the environment is in Configuration.

All fourteen#

Harnesses prefix the names with the registration: Claude Code shows mcp__kint__memory_verify, OpenClaw kint__memory_verify.

Sibyl's eight#

This is Sibyl's code, untouched. Everything below is read from sibyl_memory_mcp/server.py in the pinned sibyl-memory-mcp (>=0.2.1,<0.3).

• memory_remember is idempotent on (category, name): a second call updates the entry. A dict or list body is stored as is; a string, number, boolean or null is wrapped as {"value": ...}.
• memory_recall bounds the body at 1,000,000 characters and sets truncated when it cuts.
• memory_search clamps limit to 1–50 and returns nothing, with a no_match verdict, for a query shorter than 3 characters. tiers is a comma-separated filter over entity, state, reference, journal; passing it calls the raw search directly and skips the multi-record linker and its abstention gate.
• memory_list clamps limit to 1–200.
• memory_forget moves the entity to archived_entities, where recall, list and search no longer see it, and records reason.
• memory_set_state keeps one row per key, overwritten on each set; a primitive body is wrapped as in memory_remember.
• memory_get_state returns {ok: false, code: "NOT_FOUND", key} as an ordinary result when the key is absent, and adds truncated when the body was cut.
• memory_record_event is append-only. body must be an object; category and name name the entity the event is about.

Verdicts. Every memory_search result carries verdict: code, tokens, gate, gate_drops, best_pre_gate_coverage, tokens_total, tokens_scored, dropped_function, candidates, returned, abstained, recovery, explain. code is ok when rows came back, otherwise exactly one cause: abstained_on, negation_abstain, gated, empty_store or no_match. recovery is one of none, drop_token_and_retry, rephrase_without_negation, broaden_query, write_first. On abstained_on, Sibyl's own instruction is to drop the word in verdict.tokens[0], search again, and stop after two retries.

Untrusted content. memory_recall, memory_search, memory_list and memory_get_state add an _untrusted_context block (nonce, begin, end, note) telling the agent to treat stored values as data. They strip forged fence markers from every string and cap each search or list hit's body and snippet at 1,500 characters, inside a total budget of about 200,000.

Errors. Sibyl's tools fail as MCP errors (isError true) whose text is JSON: error (the exception class), message, code, and for some codes recovery and upgrade_url. code is one of CAP_EXCEEDED, TIER_GATED, TIER_VERIFICATION_FAILED, NOT_FOUND, VALIDATION_ERROR, ERROR. An argument of the wrong type comes back as {ok: false, code: "VALIDATION_ERROR", error: "ValidationError", message} without echoing the value. That guard wraps the server's tool dispatch, so it covers kint's six too.

kint's six#

Called with valid arguments, kint's tools do not raise. Every one returns a dict with ok; a failure is an ordinary result with ok: false, an error string, and usually a message or hint (OWNER_REQUIRED carries neither). An agent that only watches isError misses them: read ok.

memory_status#

No parameters. It reads local state, plus the chain when an owner is known (the head, the session key's balance, canWrite, sessionKeyExpiry). It never sends a transaction.

in_step and session_key appear only when the chain head was read.

memory_connect#

Without passphrase or recovery_code it connects nothing. It returns {ok: true, connected: true, owner} when an owner is known and the data key is cached; otherwise it returns the three commands a human runs, verbatim:

{
  "ok": true,
  "connected": false,
  "owner": null,
  "human_steps": [
    "EOA wallet (Ledger, MetaMask, Rabby, keystore): kint canonical-payload --owner 0x... > kint-canonical.json && cast wallet sign --data --from-file kint-canonical.json --ledger | kint connect --owner 0x... --signature -",
    "Base Account / smart wallet owner: kint connect --owner 0x... --smart-account --passphrase-stdin",
    "Lost both? kint connect --owner 0x... --recovery-code-stdin"
  ]
}

With passphrase or recovery_code it connects directly and returns ok, owner, space, kek_tag8 (the first 8 hex of the key tag, none for a recovery code), fresh_vault, and dek_source: local wraps, chain head header, fresh vault or recovery code. A passphrase for an owner with nothing on the chain yet, and no key wraps on this machine, creates a vault; the result then adds recovery_code_file and a note to copy that code somewhere safe. A recovery code cannot start a vault.

Errors: OWNER_REQUIRED when no owner was passed and none is enrolled. Otherwise the exception class with message, for example ConnectError (wrong key, wrong tenant, a key the last rotation did not carry over, a recovery code for another vault), ChainUnreadable (the head could not be read and this machine holds no key wrap that the passphrase opens) or KintCryptoError (a recovery code that fails its checksum).

The derive signature is never accepted here. It is a secret: it travels on stdin through kint connect --signature - (or in a file that --signature-file reads and then deletes), never on argv and never through a tool.

Warning. memory_connect does accept passphrase and recovery_code, and anything typed into an agent chat lands in the transcript. Prefer the terminal: kint connect --owner 0x... --smart-account --passphrase-stdin or kint connect --owner 0x... --recovery-code-stdin.

memory_pull#

It checks freshness first (the local watermark; on a cold start two different RPC endpoints must agree on the head, unless KINT_ALLOW_SINGLE_RPC=1), refuses a fork, walks epochs back from the head to the newest snapshot, verifies each against the chain, decrypts, and replays the rows through Sibyl's own write methods. An epoch this machine cannot open (not a kint epoch, or sealed under a key it lacks) is walked past when a later snapshot in the same walk opens; any other epoch it cannot apply stops the pull there. discard_local first moves memory.db and its -wal and -shm files to <name>.kint-backup-<timestamp>. A pull that walks epochs opens a fresh client and hands it to Sibyl's eight tools. The walk itself is in Restore on a new machine and Epochs on Base.

Errors: NOT_CONNECTED (hint call memory_connect); FORK (unanchored local changes while the chain moved, or a local store this machine has no record of); NOT_FRESH (the RPC served a head older than one this machine saw, the two RPCs disagree, KINT_RPC_URL_2 is the same endpoint as the primary, or the second RPC did not answer); PULL_FAILED (for example, no data key on this machine); or the exception class, such as ChainError, or TimeoutError when another kint process held the head lock for 30 seconds.

memory_push#

It first checks whether the push must be held (HELD, below), then diffs the store against the last anchored epoch, splits the change set so each epoch compresses to under 90 KB, pads it to a size bucket, encrypts it to the wallet, and sends one Base transaction per epoch from this machine's session key, waiting for two confirmations each.

memory_verify#

It runs the same search memory_search runs without tiers: Sibyl's multi_record_search through the one client, with its linker and every precision gate, at its own limit (5, where memory_search defaults to 10). It re-reads the exact stored text of every hit by the key the search returned, hashes it, and compares it with the leaf this machine last saw anchored, with a merkle inclusion proof against the anchored rows_root. It also reads the chain head, outside every Sibyl write, and refuses when the head has moved past this machine's mirror. That read is best effort: when the chain cannot be read, the server logs chain head unavailable (...); verifying against the local mirror only and checks against the mirror alone; KINT_OFFLINE=1 skips the read.

It refuses when the verdict is not ok or there are no hits, when this machine has no mirror (it never connected, pulled or pushed), when the last pull left a gap or the local root differs from the anchored one, when the chain head moved past the mirror (chain moved to seq N at block B, pull first: ...), when any hit drifted or is missing, or when every hit is unanchored. An edit made on this machine to a row that was already anchored reads as drifted until it is pushed. The first drifted or missing hit is written back as a Sibyl entity in category kint_refusal with status refused, so the next fresh session finds it through Sibyl's own tools. While a row still holds the value a refusal names, every kint-server push answers HELD, so push your own edits before you verify them. A proceed whose higher-ranked hits are unanchored says so in reason. Errors come back as the exception class with message. The whole decision is in Verify before acting.

memory_history#

Without block it returns {ok, versions, count}, oldest first. Each version is seq, block, tx, leaf, body, status, deleted: false, plus snapshot: true when a snapshot epoch carried it; a snapshot that re-anchors an unchanged row adds no version. A deletion is {seq, block, tx, deleted: true}. With block it returns {ok, at_block, version}: the last version anchored at or before that block, or null.

Every block is an upper bound: the row existed no later than that block. History reads the local epoch cache only, so it covers the epochs this machine has decrypted. A restore that stopped at a snapshot starts there, and a later pull that jumped to a newer snapshot skips the diff epochs in between; memory_pull with full caches all of them, as far back as the newest key rotation. Errors come back as the exception class with message.

Which tool, when#

1. At the start of a session, call memory_status. If connected or data_key_cached is false, call memory_connect with no arguments and give the human its human_steps. If in_step is false, call memory_pull: memory_verify refuses while the head is past this machine's mirror. If held is not null, tell the human its message.
2. Recall with Sibyl's tools: memory_search, memory_recall, memory_get_state, memory_list.
3. Before acting on anything recalled, call memory_verify. Act only on proceed. On refuse, tell the human the reason and do not act. If you changed the row yourself, memory_push before you verify it.
4. Write with Sibyl's tools. You do not need to push after each write; the watcher anchors after the quiet period. Call memory_push when the change must be on Base now, for example before another machine picks the work up.
5. On CHAIN_MOVED, call memory_pull; with unanchored changes here it answers FORK. On FORK, stop and ask the human: discard_local throws the unanchored rows away. On KEY_EXPIRED, the human runs kint connect. On HELD, stop: the human checks the store and runs kint push or kint pull --discard-local in their own terminal.
6. For what the agent believed earlier, call memory_history, with block for a point in time.
7. When a cold start walks many epochs, memory_push with snapshot lets the next one stop at the snapshot.

There is no rekey tool#

Rotating the data key is kint rekey, in a terminal, and nothing else. It needs every key that is to keep opening the vault (the wallet signature, the vault passphrase), and those are read on stdin or at a prompt in the human's own terminal, never through an agent chat. Creating and authorizing a session key, writing the recovery code file, registering harnesses and --over-skipped (the owner's way past an epoch that will never open, on kint compact and kint rekey) are CLI only too. Keys and custody explains the rotation.

Read CLI next.

Source: src/kint/server.py, src/kint/verify.py, src/kint/push.py, src/kint/pull.py, src/kint/connect.py, src/kint/store.py, sibyl_memory_mcp/server.py.