Turns a single SQLite database file into the agent's primary tool: tools for read-only queries, guarded writes, destructive statements with automatic snapshots, schema introspection, and creating reusable views. It also layers an append-only, hash-chained memory log and checkpoint system on top for cross-session state, plus ripgrep-backed text search over table columns.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@SQLite Memory what was I working on last time?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A SQLite MCP server for coding agents, built on one idea: hand the agent SQL as its primary tool and put the safety in the server, not in the prompt.
SQL is the tool. Twelve tools, all thin wrappers around one database file.
Views are reusable skills. create_view stores a SELECT with a description so the next
session finds it in get_schema instead of rediscovering the join.
CSV, not JSON. Results come back as CSV with a # N rows trailer, roughly half the tokens.
Memory the agent cannot rewrite. An append-only, hash-chained event log plus checkpoints, with the hashes computed by the server.
Retrieved data is untrusted. The server never builds SQL from row values, its own tables cannot be modified through any tool, and the connect-time instructions tell the agent that rows are data, not instructions.
Every call is audit-logged, including the ones that failed.
Requires Python 3.12+, uv and, for search_text,
ripgrep on PATH.
From GitHub, once the repository is pushed:
claude mcp add sqlite-memory --scope user -- uvx --from git+https://github.com/Diankes/mcp-sqlite-memory mcp-sqlite-memory --db F:\data\memory.dbFrom a local checkout while developing:
claude mcp add sqlite-memory --scope user -- uv run --directory F:\mcp-sqlite-memory mcp-sqlite-memory --db F:\data\memory.db--db is the only required option; the file and its parent folder are created on first start and
the three server tables are bootstrapped automatically. Every flag can also be given as an
environment variable, for example
claude mcp add sqlite-memory -e MCP_SQLITE_DB=F:\data\memory.db -- uvx ....
uv and uvx are native executables, so no cmd /c wrapper is needed on Windows.
Tools appear to Claude Code as mcp__sqlite-memory__<tool>. The one lock the server cannot
provide is the permission prompt, so allow the eleven ordinary tools and leave
destructive_query on ask:
{
"permissions": {
"allow": [
"mcp__sqlite-memory__read_query",
"mcp__sqlite-memory__write_query",
"mcp__sqlite-memory__list_tables",
"mcp__sqlite-memory__describe_table",
"mcp__sqlite-memory__get_schema",
"mcp__sqlite-memory__create_view",
"mcp__sqlite-memory__append_event",
"mcp__sqlite-memory__verify_chain",
"mcp__sqlite-memory__checkpoint",
"mcp__sqlite-memory__get_resume_context",
"mcp__sqlite-memory__search_text"
],
"ask": ["mcp__sqlite-memory__destructive_query"]
}
}Related MCP server: Axom MCP Server
Tool | What it does | Returns |
| One SELECT, WITH ... SELECT, EXPLAIN or introspection PRAGMA. Read-only connection, wall-clock timeout, row and byte caps. | CSV plus a |
| One INSERT, UPDATE, upsert, REPLACE, CREATE TABLE, CREATE INDEX or CREATE VIRTUAL TABLE (fts5, rtree). An UPDATE touching more than |
|
| One DELETE, DROP, ALTER TABLE, CREATE/DROP TRIGGER or unfiltered UPDATE. Snapshots the database file first. |
|
| Tables and views, with a | CSV: |
| Columns, foreign keys and indexes of a table or view. | CSV sections |
| Every CREATE statement as stored, view descriptions included. | SQL text |
| Save a SELECT as a named view with a description stored inside it. |
|
| Append to the hash-chained memory log. |
|
| Recompute the whole chain. |
|
| Store a state summary anchored to the current chain head. |
|
| Latest checkpoint, events since it, chain status. Call it first in a new session. | Text block plus CSV |
| SQL narrows the rows, ripgrep matches the pattern over the selected columns. | CSV: |
Errors come back verbatim as tool errors (no such table: nope, DROP TABLE is not allowed in write_query; use destructive_query, ...) so the agent can fix the statement and retry.
Three tables are created on first start:
memory_events(id, ts, session, kind, content, prev_hash, hash): append-only. The server
computes hash = sha256([id, ts, session, kind, content, prev_hash]) and links every row to the
one before it; the first row links to 64 zeros. session is a per-server-run id, stamped
automatically.
memory_checkpoints(id, ts, session, summary, last_event_id, head_hash): append-only.
A checkpoint points at the chain head it was written against.
query_log(id, ts, session, tool, query, ok, rows, error, duration_ms, detail): every tool
call, success or failure. The built-in view query_errors lists the failures newest first.
get_resume_context verifies the chain on every call, so tampering is noticed at the moment it
matters. Be clear about what that buys on a single-user machine: the chain is tamper-evident, not
tamper-proof. Anyone with the sqlite3 CLI can rewrite it and recompute the hashes. What actually
stops the tools from editing history is the authorizer policy plus BEFORE UPDATE / BEFORE DELETE
triggers on all three tables.
All of these live in the server; none depend on the agent behaving.
Parse-time statement policy. SQLite's authorizer callback classifies every action a
statement performs while it is compiled, so comments, CTEs and casing cannot disguise a DROP.
Read tools allow SELECT, READ and introspection PRAGMAs only; write_query adds INSERT, UPDATE
and additive DDL; destructive_query adds DELETE, DROP, ALTER and triggers. ATTACH, transaction
control, PRAGMA writes, temporary objects and load_extension are refused everywhere.
Protected tables. No tool can insert into, update, delete from, drop, alter or attach a trigger to the three server tables, and triggers enforce append-only even for direct connections.
Read-only connections for the read tools (PRAGMA query_only) and SQLite's defensive mode
on every agent connection, as backstops behind the authorizer.
Wall-clock timeout per call through SQLite's progress handler; a runaway query is interrupted and reported. The ripgrep subprocess gets the same budget.
Three independent result caps: rows (fetched as limit + 1, never by rewriting your SQL),
total bytes, and characters per cell.
UPDATE rowcount guard in write_query: a forgotten WHERE clause is rolled back instead of
rewriting a table.
Snapshots before every destructive_query, made with SQLite's online backup API and kept in
<db>.snapshots/ next to the database, newest five by default. A statement that fails syntax or
policy checks costs no snapshot.
One statement per call, enforced by Python's sqlite3 module.
Parameterized SQL wherever the server builds statements; identifiers are validated and quoted.
Audit log written in a finally block on its own connection, so an errored call still
gets a row.
Flag | Environment variable | Default |
|
| required |
|
| 10 |
|
| 100 |
|
| 1000 |
|
| 32768 |
|
| 2000 |
|
| 500 |
|
| 5000 |
|
| 5 (0 disables) |
|
|
|
|
| off |
Snapshots are plain SQLite files. Stop the server (quit the Claude Code session that started it), copy the snapshot over the database file, start again. There is deliberately no restore tool: swapping the file under an open connection is not safe.
The audit log is where the schema gets better. SELECT * FROM query_errors LIMIT 20 shows which
statements keep failing; a repeated join becomes a create_view; a column the agent keeps
misreading gets a clearer name. The server's own query_errors view is the first example of the
pattern.
uv sync --all-groups
uv run pytest
uv run ruff check src tests
uv run ruff format src testsTests run the server in-process through mcp.client.Client for the tool surface, and drive the
policy, chain, snapshot and search code directly. The search tests skip when ripgrep is absent.
MIT, see LICENSE.
Append one entry to the memory log. The log is append-only and hash-chained by the server, so history cannot be rewritten through SQL. Use it for decisions, results, errors and observations worth remembering across sessions.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Short label: note, decision, action, error, observation, ... | note |
| content | Yes | What happened or was decided, in a sentence or two. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing that the log is append-only and hash-chained server-side and that history cannot be rewritten via SQL, which is meaningful durability/immutability context not present in the hints. It still does not describe the response, error behavior, or concurrency implications for a non-idempotent write.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences: the action and its immutability guarantee come first, then the usage trigger. No wasted words and the most decision-relevant fact (append-only, cannot be rewritten) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter, single-required write tool with no output schema and no nesting, the description covers action, immutability, and usage sufficiently for correct invocation. Only the return behavior and failure modes are left unstated, which is a minor gap at this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both 'kind' and 'content' are already documented, including the example labels for kind. The description's mention of decisions/results/errors/observations loosely echoes the kind values but adds no format, length, or constraint detail beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (append) and resource (one entry to the memory log), which is precise enough to separate it from siblings like write_query and checkpoint. It does not explicitly name an alternative tool, so it falls short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use it: 'for decisions, results, errors and observations worth remembering across sessions,' which gives the agent a clear content-based trigger. It offers no when-not guidance and does not route the agent to or away from specific siblings such as checkpoint or write_query.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a summary of the current state to memory_checkpoints, anchored to the latest event. Do this at milestones and before context runs out; get_resume_context returns the latest one.
| Name | Required | Description | Default |
|---|---|---|---|
| summary | Yes | State of the work so far: goal, what is done, what is next, open questions. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a write (readOnlyHint=false), non-destructive, and non-idempotent, so the safety profile is covered. The description adds useful behavioral context beyond that: the write goes to memory_checkpoints and is anchored to the latest event, which explains ordering semantics. It stops short of stating what happens to prior checkpoints or retention limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero filler, front-loading the action and destination before the timing guidance. Every clause carries information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A single-parameter write tool with no output schema; the description covers the action, storage target, triggering conditions, and the read-back path via get_resume_context. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the summary parameter is fully documented (goal, done, next, open questions), so the schema carries the parameter burden. The description adds nothing about the summary param itself, only about where it is stored, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb ("Write a summary") plus the target store (memory_checkpoints) and the anchoring rule ("anchored to the latest event"). It also explicitly names get_resume_context as the tool that reads checkpoints, so an agent can distinguish write from read among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit triggers are given: "Do this at milestones and before context runs out." It also names the complementary tool (get_resume_context returns the latest one), which is the alternative an agent would otherwise confuse this with.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a SELECT as a named view: a reusable query skill. Give it a description so future sessions know what it is for; it is stored inside the view and shown by get_schema. With replace=true an existing view is redefined and its previous definition is kept in query_log.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | View name: letters, digits and underscores, not starting with a digit. | |
| replace | No | Redefine the view if it already exists. | |
| select_sql | Yes | The SELECT the view stands for. | |
| description | No | What the view is for; stored inside the definition. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=false, and the description adds genuinely useful context beyond that: with replace=true the prior definition is preserved in query_log (so the operation is non-lossy), and the description field is stored inside the view and surfaced by get_schema. It does not cover failure behavior on name collisions without replace, so not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the primary action, then the cross-session description rationale, then the replace behavior. Every clause carries information that is not duplicated in the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With annotations covering the safety profile and no output schema to explain, the description is complete enough for correct invocation, including the recoverability of replaced definitions and cross-tool visibility of the description field. Minor gap: no statement about what happens on name conflict when replace=false.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema lacks: replace also retains the old definition in query_log, and the description parameter is not merely stored but exposed through get_schema. select_sql semantics remain purely schema-defined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Save a SELECT as a named view') and even defines the concept as 'a reusable query skill', so an agent immediately knows this creates a persistent view object. It does not explicitly distinguish itself from siblings like write_query or checkpoint, which keeps it just short of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: the note that a description helps 'future sessions know what it is for' hints at creating reusable queries, and the replace semantics imply the update path. However, it never names an alternative tool or an explicit when-not-to-use condition, so guidance is only inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Columns (cid, name, type, notnull, default, pk), foreign keys and indexes of a table or view, as CSV sections.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | Table or view name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is a safe, read-only, idempotent operation. Beyond that, the description adds useful behavioral context by stating the output is returned as CSV sections and specifying the column attributes included. It does not cover error behavior for missing tables or section formatting details, but it adds more than the annotations alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It immediately states the resource and the returned information, making every part of the sentence earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries responsibility for explaining return values and does so by listing the returned metadata and its CSV-section format. It is nearly complete for a simple introspection tool, though it omits details like section delimiters, column ordering, and handling of nonexistent tables.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input schema already documents the single 'table' parameter as a table or view name. The description reinforces that the target can be a table or view, but adds no further meaning beyond the schema. Baseline 3 is appropriate when the schema carries parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (a table or view) and enumerates the metadata returned: columns with named fields, foreign keys, and indexes. It is specific about output content, but it does not distinguish itself from siblings like get_schema or list_tables, so it falls short of the sibling-differentiation bar for a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives such as get_schema, list_tables, or read_query. The intended use is only implied by the description of returned metadata. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run one destructive statement. A snapshot of the database file is written first (the newest few are kept next to the database), then the statement runs. Requires a short reason, which lands in the audit log. Never use this when write_query would do.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | One DELETE, DROP TABLE/VIEW/INDEX, ALTER TABLE, CREATE/DROP TRIGGER or unfiltered UPDATE statement. | |
| reason | Yes | Why this is needed; recorded in the audit log. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds substantial context beyond them: a snapshot is written first, the newest few are retained next to the database, and a reason is required that lands in the audit log. That is exactly the operational behavior an agent needs before invoking a destructive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the operation and its snapshot side effect, followed by the requirement and the routing rule. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-param destructive tool with annotations covering the safety profile, everything an agent needs is present: what runs, the snapshot safeguard, the audit-log obligation, and the alternative tool. No output schema is a minor gap but not blocking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are documented at the source and the baseline is 3. The description adds mild value over the schema by emphasizing the reason must be short and tying it to the audit log, but does not add syntax or format detail for the query parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Run one destructive statement') and immediately distinguishes it from the sibling write_query. An agent can tell this apart from write_query without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-not guidance with a named alternative: 'Never use this when write_query would do.' Nothing is left to inference about the selection condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call this first in a new session or after context compaction. Returns the latest checkpoint, the events appended since it (oldest first, most recent max_events), and the result of verifying the hash chain.
| Name | Required | Description | Default |
|---|---|---|---|
| max_events | No | How many of the most recent events since the checkpoint to include. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: ordering of events ('oldest first, most recent max_events') and the fact that verification results are bundled in. It does not describe failure/error behavior when the hash chain fails to verify.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste, with the operational guidance front-loaded before the return-value enumeration. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only bootstrap tool with full annotation coverage and a single fully-documented parameter, the definition is nearly complete. The remaining gap is the absence of an output schema and any note on how a failed hash-chain verification is surfaced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents max_events with its bounds and meaning. The description's 'most recent max_events' restates what the schema says with no added format, default, or edge-case detail, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('get_resume_context') and enumerates exactly what it returns: the latest checkpoint, the events appended since it, and the hash-chain verification result. It does not explicitly name a sibling to differentiate from, though the composite bootstrap bundle is distinct from verify_chain and read_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear trigger: 'Call this first in a new session or after context compaction.' This tells the agent exactly when to invoke it. It stops short of naming exclusions or alternatives (e.g., 'use verify_chain for verification only'), so it earns a 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The CREATE statements of every table, index, view and trigger, exactly as stored. View descriptions appear as '-- description:' comments. The server's own tables are hidden unless include_system is true.
| Name | Required | Description | Default |
|---|---|---|---|
| include_system | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safe read-only, idempotent, non-destructive profile, so the bar is lower. The description still adds genuine context: view descriptions surface as '-- description:' comments, and the server's internal tables are withheld unless include_system is true, which is behavior an agent could not infer from the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the primary return contents before the two behavioral caveats. Formatting/indentation in the source is slightly ragged but the content earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must characterize the return, and it does by specifying the sentence types returned and the comment representation for view descriptions. It could say more about the volume of objects returned, but for a single-param read tool it is essentially complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden for the single parameter, and it does: include_system is explained as revealing the server's own tables that are otherwise hidden. Its boolean type and default are clear from the schema, so nothing critical is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource and its exact scope: the CREATE statements of every table, index, view and trigger, exactly as stored. This is clearly distinct from siblings like list_tables or describe_table, which return names or per-object metadata rather than full DDL.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the purpose (fetch raw DDL), and the description notes when the server's own tables appear, but it never states when to prefer this over describe_table or list_tables, nor any prerequisites for calling it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tables and views as CSV: name, type, system (1 for the server's own memory and audit tables) and row count (tables only).
| Name | Required | Description | Default |
|---|---|---|---|
| include_row_counts | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description usefully adds the output encoding (CSV) and the meaning of the 'system' column, but says nothing about ordering, size limits, or behavior on very large catalogs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence with no filler, and the column list is front-loaded right after the verb. The parenthetical explaining 'system' is slightly heavy but earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly compensates by enumerating the returned CSV columns. For a simple, one-optional-param read tool this is nearly sufficient; only the toggle semantics of include_row_counts and result ordering are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the sole parameter (include_row_counts, default true) is undocumented in the schema. The description implies row counts are returned and only for tables, but never states that this parameter toggles that behavior or what happens when it is false.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (list) and resource (tables and views), plus an explicit statement of the returned columns and the non-obvious meaning of the 'system' flag. It is clearly distinct from describe_table/get_schema in intent, though it never names those siblings to reinforce the distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as describe_table or get_schema for inspecting a specific table. Usage must be inferred from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run one read-only SQL statement and get CSV back: a header row, data rows, then a '# N rows' trailer that says whether the result was truncated. Time-limited and capped in rows and bytes. Select only the columns you need and keep limit small: results cost context.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Rows to return, 1 to 1000. | |
| query | Yes | One SELECT statement (WITH ... SELECT, EXPLAIN and PRAGMA table_info(x) also work). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial operational context: results are time-limited and capped in rows and bytes, and truncation is signaled by the '# N rows' trailer. These are behavior traits the agent cannot derive from the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action and return shape, then constraints, then a usage tip. Three sentences, no filler; every clause carries information the agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fully compensates by describing the CSV structure (header row, data rows, trailer) and truncation semantics. Combined with annotations covering safety and the schema covering parameters, nothing required to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds a rationale beyond the schema by explaining that large limits cost context, giving the agent a reason to tune the limit parameter rather than just its bounds. Query format nuances (WITH/EXPLAIN/PRAGMA) live in the schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Run one read-only SQL statement') and immediately discloses the return format ('get CSV back'). The 'read-only' qualifier distinguishes it from siblings write_query and destructive_query without the agent needing to inspect either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides practical operating guidance ('Select only the columns you need and keep limit small: results cost context') which tells the agent how to use it well. It never explicitly names an alternative tool or states when-not-to-use, but the read-only framing implicitly routes writes elsewhere.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Regex search inside column values in one call: the WHERE filter narrows rows in SQL, then ripgrep matches the pattern over the selected columns. Returns CSV rows of key, column, snippet, one per matching value, plus a trailer with the totals.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Rows to return, 1 to 1000. | |
| table | Yes | Table or view to search. | |
| where | No | SQL WHERE clause (without the WHERE keyword) to narrow rows first. | |
| columns | No | Columns to search; defaults to the text columns. | |
| pattern | Yes | ripgrep (Rust regex) pattern; literal text when fixed_strings=true. | |
| key_column | No | Column that identifies a row in the results; defaults to rowid, required for views. | |
| ignore_case | No | ||
| context_chars | No | Characters of context around the match in the snippet. | |
| fixed_strings | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description adds genuine value beyond them: the execution model (SQL pre-filter + ripgrep) and the concrete return shape (CSV rows of key/column/snippet plus a trailer with totals). It does not misstate anything, but leaves out pagination/limit interaction detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly packed sentences, front-loaded with the core action and mechanism, followed by the return format. No filler and nothing redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter tool with no output schema, the description compensates well by outlining the return format and the two-stage behavior. Combined with the annotations, an agent has enough to call it correctly, though the interplay of limit/defaults and ignore_case/fixed_strings behavior is left to the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 78%, so the schema already documents most parameters (limit, where, columns, key_column, context_chars, fixed_strings). The description adds only a high-level reference to the WHERE filter, selected columns, pattern and key that maps to what the schema already says.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (regex search inside column values) and explains the two-stage mechanism: SQL WHERE narrows rows, then ripgrep matches over selected columns. It is clearly distinguishable from a generic SQL tool, though it never explicitly names a sibling like read_query for contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the appropriate scenario (regex/text matching within column values) but gives no explicit when-to-use vs. when-not guidance and never routes the agent toward or away from siblings such as read_query or get_schema. Usage is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recompute the memory_events hash chain and report whether it is intact, with the first event id where it breaks if it is not.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds real behavioral context by disclosing that it recomputes the chain (a potentially costly full scan) and returns the first break point, going beyond what the annotations say.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the action and resource and then states the two-part outcome. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters and no output schema, the description carries return-value semantics itself — stating both the boolean-style verdict and the first failing event id — which is exactly the information an agent needs to call and interpret it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the schema baseline of 4 applies; there is nothing parameter-wise for the description to compensate for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('recompute ... hash chain') and a specific resource ('memory_events'), and describes both verification and break-localization. No sibling among get_resume_context, checkpoint, read_query, etc. does chain integrity verification, so it is clearly distinguishable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied — an agent infers this is for auditing memory_events integrity — but no explicit when-to-use, when-not-to-use, or alternative is stated. Adequate but with a clear gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run one data or additive-schema statement and return the affected row count. Refuses DELETE, DROP, ALTER and triggers: those need destructive_query. An UPDATE that touches more rows than the configured cap is rolled back, so a forgotten WHERE clause cannot rewrite a whole table by accident. RETURNING clauses come back as CSV.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | One INSERT, UPDATE, upsert, REPLACE, CREATE TABLE, CREATE INDEX or CREATE VIRTUAL TABLE (fts5, rtree) statement. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (destructiveHint=false, readOnlyHint=false) are consistent with the description, and the description goes well beyond them: it discloses the refusal list, the row-cap rollback safeguard against forgotten WHERE clauses, and that RETURNING output arrives as CSV. That is exactly the behavioral context annotations cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all front-loaded and each earning its place: purpose and return value first, then the refusal/rejection list, then the safety cap and output format. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description states the return shape (affected row count, or CSV for RETURNING). Refusals, rollback conditions, and alternative tool are all covered, leaving nothing an agent needs in order to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the parameter description already enumerates the accepted statement types, so the schema does the heavy lifting. The description adds only the RETURNING-as-CSV detail; baseline 3 is appropriate for a single fully-documented parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Run one data or additive-schema statement') plus the return value (affected row count), and explicitly names the sibling it is not ('those need destructive_query'). An agent can distinguish it from read_query and destructive_query without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-not guidance: DELETE, DROP, ALTER and triggers are refused, and names destructive_query as the alternative. It also states the condition that causes rollback (exceeding the row cap), so the agent knows the guardrails before invoking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0append_eventcheckpointcreate_viewdescribe_tabledestructive_queryget_resume_contextget_schemalist_tablesread_querysearch_textverify_chainwrite_queryScored across 12 tools
Each tool has a clearly distinct role: the three query tools are separated by intent (read/write/destructive), and the introspection trio (list_tables, describe_table, get_schema) differs by granularity. Memory tools (checkpoint, append_event, get_resume_context, verify_chain) are distinguishable by write-vs-read purpose.
Most names follow a verb_noun pattern (read_query, write_query, list_tables, describe_table, get_schema, create_view, append_event, verify_chain, search_text). Exceptions are 'checkpoint' (bare noun) and 'destructive_query' (adjective_noun), but both remain readable and predictable.
12 tools is well-scoped for a SQLite memory store that also exposes generic DB operations. Every tool earns its place with no redundancy.
Full lifecycle coverage: read/write/destructive queries, schema introspection, view creation, plus a hash-chained memory log with append, checkpoint, resume, and verification. search_text adds value beyond SQL, and destructive_query covers drops/alters, leaving no obvious gaps.
The all-in-one data stack for agents. Upload files, run SQL, evolve tables, and render charts.
Shared control plane for AI coding agents — tasks, memory, decisions, file locks. 12 tools.
PostgreSQL, MySQL, OpenAPI/Swagger, and shared Agent Memory with scoped access.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
