MemCore
MemCore is a local, shared memory store for AI assistants — one SQLite database of durable facts that every tool reads and writes.
Search across every scope with
memory_search— FTS5 lexical search (strict AND, then ranked OR fallback) blended with optional semantic/vector search;debugreveals which path matched.Retrieve a known entry by exact scope + name with
memory_get.Browse without a query using
memory_list— by scope, by type (user/feedback/project/reference), or archived-only.Catch up on changes with
memory_recent(newest first, per-scope or global).Write or update facts via
memory_write— upserts on scope + name, optionalexpected_updated_atoptimistic lock to avoid clobbering concurrent edits, and automatic secret redaction.Soft-delete and undo with
memory_archive/memory_restore, both requiring a reason that lands in the audit log.Recover past content with
memory_history— prior versions of overwritten or deleted entries.Audit who did what with
memory_events— writes, conflicts, restores and redactions, with actor and origin.Inspect the store via
memory_scopes(scopes + counts),memory_stats(totals, archived count, DB path) andmemory_embed_status(model and embedding coverage).Verify the connection with
memory_healthcheck, an end-to-end write/read/search/history/delete test on a throwaway scope.Operate within guardrails — read-only and scope-locked connections are enforced server-side, so writes and reads stay confined to what the connection is permitted.
MemCore
Your AI finally remembers.
A single local database of the things worth keeping — decisions, corrections, "we already tried that" — shared by every AI tool you use, searchable in plain language, across every project.
No daemon. No cloud. No telemetry. One SQLite file you own.
You've had this conversation
You're deep in a project with an AI agent. It's flying. Then the context window fills, or you close the terminal, or it's simply tomorrow — and you're back to square one with someone who has no idea who you are.
You re-explain the constraints. You re-explain, again, that "we already tried the buffered approach and it deadlocks." You spent an hour last Tuesday arguing through a design trade-off; today the agent proposes the exact option you threw out.
And then it gets worse — it starts making things up:
You: Remember in the payments project, when we fixed the double-charge bug? What did we actually change?
Agent: Yes — we added an idempotency key on the request, moved the retry logic behind a mutex, and set the timeout to 8 seconds.
None of that happened. You're not even in the payments repo right now. The agent had nothing real to work from, so it produced something that sounds right — and you only catch it because you remember. Most days, you don't.
Now multiply that by every tool on your machine. One agent doesn't know what you told another. Each wakes up blank, every single time. You have become the memory. That's the bug.
Related MCP server: Memory MCP
MemCore fixes it
MemCore is one small local database of durable facts — the decisions, the corrections, the "here's how this actually works", the "we ruled this out and here's why". Every AI tool you run reads and writes the same store.
Ask before you re-explain:
memory_search "why did we drop the queue-based design"
projectnote, from three weeks ago: "queue design deadlocked under load on 2026-08-02, reverted to direct calls." — written in a different repo, found anyway.
And when there's nothing to find, it says so — a plain no match, not a confident answer improvised to fill the silence.
Corrections that finally stick. Tell it once that the API returns cents, not dollars; write it down; the next session — and the next tool — starts already knowing.
A paper trail. Every write is logged with who and when. Overwrites keep the old version. Nothing is ever silently lost.
What it feels like
Coming back:
You: back — where were we?
(agent:
memory_recent,memory_search)Agent: Last real change, 40 minutes ago: v1.0.84 shipped, replacement parts ordered, waiting on delivery. You were about to start the user guide. Nothing else moved.
Not a guess. Not a stale summary. The actual state, reconstructed from what was recorded.
The cross-project question — answered straight:
You: we standardised on the EU date format everywhere, right?
Agent: (
memory_search "date format") Yes —feedback, global scope, still current. And there's a follow-up note: the CSV export is the one exception, it stays ISO-8601.
Onboarding a fresh agent to a codebase:
memory_list --scope my-project --type feedbackEvery lesson the last ten sessions learned about this repo, in one list — before it writes a single line.
Not re-litigating a settled decision: the agent starts to suggest an approach, checks MemCore first, finds the note where that approach already failed, and suggests something else. You never even see the wrong turn.
Closing out:
You: memcorise all of this.
(agent writes the session's durable facts — what shipped, what's still open, what we decided — into MemCore)
memcorise (verb): to write it down once, so no AI ever has to ask again.
Why the name
The core of memory. Not a transcript, not a log, not "everything the model ever saw" — the small, curated, durable part. The handful of facts that, if you lost them, you'd have to painfully earn back.
The one design decision that matters
Nothing is captured automatically. No background hooks, no daemon watching your session. An AI writes to MemCore the way it writes a note to itself — deliberately, when something is actually worth keeping. That single choice is why it's small, fast, and doesn't break: there's almost nothing to go wrong.
What it won't do
MemCore gives back the text that was written, with its scope, its date, its full edit history. Ask for something nobody ever recorded and you get no match: an honest blank, not a plausible answer improvised on the spot. The failure mode is "nothing found", which you notice, rather than "sounds right", which you don't.
It doesn't go further than that. It won't judge whether a stored fact is still true or current — that's on whoever wrote it, which is why the writing discipline further down is strict. And an assistant can still misread a result it did retrieve. What MemCore removes is the one failure you can't catch on your own: an AI filling a gap in its knowledge with invention.
A setup that works well around it
MemCore is the search layer. It pairs well with a plain-files knowledge base and a bit of discipline — the "LLM wiki" pattern (Karpathy's note):
Files as the source of truth — a Markdown vault (Obsidian works well here). Notes an AI can read, a human can edit, git can diff.
A classification an AI can trust — IPCRA or PARA: a few mutually-exclusive folders and a sort test, so it's always unambiguous what's active, what's reference, what's done. This matters double when an assistant reads the vault — the folder tells it what's live.
A schema file the assistant reads first (how you want it to behave, who it's working with). MemCore's
globalscope can hold this too.MemCore as the index — fast recall across every scope at once, the piece a folder of files alone can't give you. You keep files and index in sync; MemCore never silently rewrites your files.
An append-only log for the time-ordered view per-file notes lose, and a periodic consistency pass ("lint") for contradictions, stale paths and orphaned notes.
Pick the folder names and per-project templates that fit your work — the pattern is what matters, not the specific layout.
Features
Works with Claude Code, Codex CLI, Kimi Code, OpenCode, AgentRoom — or any tool that speaks MCP or can run a script.
Local & private | A single |
Multi-client | MCP server, CLI, line-delimited JSON bridge, or raw SQLite — all read/write the same store. |
Full-text search | SQLite FTS5 across every scope. Multi-word queries try strict AND, then fall back to ranked OR — one missing word never zeroes the result. |
Provenance & audit | Every create / update / conflict / refusal / archive / restore is appended to |
Safe concurrency | Optimistic locking via |
Reversible deletes | Archive (soft-delete) → restore. Overwritten versions kept in history. |
Per-connection access control |
|
Secret hygiene | Secret-shaped values (API keys, tokens, |
Incremental sync |
|
Semantic search (optional) | Install |
Minimal dependencies | The CLI, the JSON bridge and the importers use the Python 3.11+ standard library only. The MCP server needs one package: the official MCP SDK ( |
Install
git clone https://github.com/ManuelWarland/MemCore.git
cd MemCore
python scripts/memcore.py init # creates the database
python scripts/memcore.py healthcheck # end-to-end self-test (~1s)Database location — defaults to ~/MemCore/memcore.db. Override with the
MEMCORE_DB_PATH environment variable (point it wherever you like — a synced
folder, an encrypted volume, a project directory).
memcore.db is git-ignored — the code is shareable, your memories are not.
Semantic search (optional) — pip install -r requirements-semantic.txt
then python scripts/memcore.py embed-backfill. Adds sqlite-vec (a small C
extension) and fastembed (ONNX, no PyTorch). The default model is
paraphrase-multilingual-mpnet-base-v2 (~1 GB, downloaded once); override with
MEMCORE_EMBED_MODEL. Turn it off without uninstalling: MEMCORE_SEMANTIC=0.
Background embedding (MCP server only): after a write, the server embeds
the pending entries within a few seconds, without slowing the write. When
several servers share the same database (one per AI session), a lease in the
database lets only one of them load the model for this work. The worker starts
90 s after the server, so it never competes with the client's own startup.
Settings: MEMCORE_AUTO_EMBED=0 turns it off, MEMCORE_AUTO_EMBED_DELAY
(seconds, default 90) and MEMCORE_AUTO_EMBED_INTERVAL (seconds between idle
checks, default 10). Read-only connections never run it.
Model unloaded when idle: a process drops the model after 10 minutes
without a search or an embedding, and loads it again on the next one (in the
background for a server: lexical search answers meanwhile). Measured on
Windows: about 1.9 GB of private memory with the model, 0.55 GB once it is
unloaded, so each idle AI session gives back about 1.3 GB. Reloading takes
15 to 30 s on a hard disk. MEMCORE_EMBED_IDLE sets the delay in seconds
(default 600, 0 keeps the model loaded).
Updating
MemCore is a git checkout, not a package — you update it the same way you got it:
cd MemCore
git pullThat's the whole procedure. Your database is untouched — memcore.db is
git-ignored, and if a release changes the schema the next command you run
migrates it in place (forward-only, idempotent, existing entries preserved).
Read CHANGELOG.md for what changed.
python scripts/memcore.py version— what you're on right now (offline).python scripts/memcore.py check-updates— asks GitHub for the latest release tag and tells you if you're behind. Opt-in: this is the only command in MemCore that makes a network call, it never runs on its own, and it sends nothing but an unauthenticated GET.Prefer a notification? On GitHub, Watch → Custom → Releases.
Use it — as a human (CLI)
Works everywhere, no MCP support required. Everything prints JSON on stdout.
python scripts/memcore.py search "telegram rate limit"
python scripts/memcore.py recent
python scripts/memcore.py list --scope my-project # browse a scope
python scripts/memcore.py list --type feedback # all feedback entries
python scripts/memcore.py list --archived # what's archived
python scripts/memcore.py scopes
python scripts/memcore.py stats
python scripts/memcore.py version # this checkout's version + schema (offline)
python scripts/memcore.py add \
--scope "my-project" \
--type "feedback" \
--name "prefer-tabs-over-spaces" \
--description "One-line summary used for recall ranking" \
--content "The full note."
python scripts/memcore.py sync # incremental .md -> DB re-import
python scripts/memcore.py backup [--dest PATH] # consistent copy (SQLite backup API)
python scripts/memcore.py events [--scope X] [--prune-older-than-days 180]
# Semantic search (needs: pip install -r requirements-semantic.txt)
python scripts/memcore.py embed-backfill # embed entries missing a vector
python scripts/memcore.py embed-status
python scripts/memcore.py search "how do I back things up" --hybrid # FTS + vector (loads the model, ~5-15s cold)
python scripts/memcore.py search "how do I back things up" --semantic # vector onlyWhat comes back — every command prints JSON on stdout. search returns the
full entry plus a highlighted snippet and a relevance rank; recent and
list return the lighter header shape; nothing found is a plain []:
$ python scripts/memcore.py search "queue design deadlock"
[
{
"id": 1,
"scope": "payments-api",
"type": "project",
"name": "queue-ingest-dropped",
"description": "Queue-based ingest abandoned — buffered writes deadlock under load",
"content": "Load test past 200 req/s deadlocks the buffered writer. Switched to direct writes plus optimistic retry. See PR 412. Do not reintroduce a write queue without a load test that proves it holds.",
"source_path": null,
"updated_at": "2026-08-31T19:02:21.258146+00:00",
"snippet": "Load test past 200 req/s [deadlocks] the buffered writer. Switched to...",
"rank": -1.3496562315877076
}
]
$ python scripts/memcore.py recent --limit 2
[
{
"id": 3,
"scope": "payments-api",
"type": "reference",
"name": "oncall-runbook",
"description": "On-call runbook is in the wiki, not the repo",
"updated_at": "2026-08-31T19:02:21.863622+00:00"
},
{
"id": 2,
"scope": "global",
"type": "feedback",
"name": "prefers-direct-writes",
"description": "Prefers direct writes over buffering on latency-sensitive targets",
"updated_at": "2026-08-31T19:02:21.579769+00:00"
}
]
$ python scripts/memcore.py search "something never recorded"
[]type is one of user / feedback / project / reference (see
Conventions). Upsert is automatic on scope + name.
Use it — as an AI assistant (MCP)
The MCP server needs the official MCP Python SDK, version 2. Install it once with
pip install "mcp>=2,<3" (the CLI and the bridge need nothing).
Add MemCore as a local MCP server. The exact config shape differs per host — here are ones verified working:
Host | Config file | Root key |
|
Claude Code |
|
|
|
Codex CLI |
|
|
|
Kimi Code CLI |
|
| same as Claude Code |
OpenCode |
|
|
|
Claude Code example:
{
"mcpServers": {
"memcore": {
"type": "stdio",
"command": "python",
"args": ["/absolute/path/to/MemCore/scripts/memcore_mcp.py",
"--actor", "claude", "--origin", "terminal"]
}
}
}Most CLIs only read their MCP config at startup — restart the tool (new session) after editing it before concluding something is broken.
Access profiles (per connection)
Set on the connection's own args, not globally:
Profile | Args | Effect |
Full trust | (none) | Read/write, all scopes |
Read-only |
| Sees everything, cannot overwrite/delete |
Sandbox |
| Read/write limited to one scope, even if another is requested |
Most restrictive |
| Read-only view of a single scope |
Scope locking is enforced server-side and covered by an adversarial test
(scripts/test_access_profiles.py). Default recommendation: start any unproven
assistant read-only (or sandboxed), widen only after trust.
MCP tools
Tool | Params | Purpose |
|
| Full-text search across all scopes (AND→OR fallback). |
|
| Create or update. Pass |
|
| One entry. |
|
| Browse entries without a query — everything in a scope, all of one type, or what's archived. |
|
| Most recently modified entries. |
|
| Read the append-only audit log (writes, conflicts, redactions). |
|
| Previous versions of an overwritten/deleted entry. |
|
| Reversible soft-delete / undelete. |
| — | Scopes + entry counts. |
| — | Totals + DB path. |
| — | End-to-end self-test on a throwaway entry. Use before trusting a connection — search can misbehave silently while the connection looks up. |
Safe writes: before updating an existing entry, memory_get it and pass its
updated_at back as expected_updated_at. If another client changed it meanwhile,
the write is refused with conflict and nothing is lost.
Provenance: launch with --actor <name> --origin <terminal|agentroom|...> and,
if available, --session-ref <id>. Identity is fixed at server start, not chosen
per call.
For an AI reading this repository for the first time
This is a persistent memory store shared across the AI tools used on this machine.
It holds established facts, prior decisions and user preferences. If a global
scope exists, read it first (memory_search "user profile",
memory_search "collaboration rules") — it's how the person you're working with
wants assistants to behave. Then follow the discipline below.
Using it well
Reading — search first, by default
Search before you:
say "I don't know" or "there's no record of that"
ask a question the user may already have answered
propose an approach — has it been tried and rejected?
confirm or correct someone from memory
treat a surprising result as a mystery
At the start of a session: memory_recent plus a targeted memory_search to
rebuild the real state — don't guess, don't summarise from a stale mental model.
Search is cheap. The cost of not searching is the confident-lie failure this
tool exists to kill.
Writing — only what you'd hate to re-earn
Write when:
a decision was made — especially after a trade-off or a debate
a correction landed — "no, it's cents, not dollars"
a dead end was hit — "tried the queue design, deadlocked under load, reverted"
you learned how the setup actually works and it isn't in the code or docs
the user stated a preference
Don't write: a step-by-step of what you just did, anything git or the code already records, anything that only matters for this conversation, "reminders" to yourself. Write when the fact crystallises, not in a batch at the end — you'll forget half of it.
How to write one
One fact per entry. Tight kebab-case
name. Adescriptionthat says what the fact is — it drives recall ranking — not "notes about X".Pick the
typehonestly:user/feedback/project/reference.For
feedbackandproject: include why it matters and how to apply it. A rule with no rationale gets misapplied or ignored.Relative dates → absolute ("last Tuesday" → the actual date).
Update the existing entry (same
scope+name) — don't create a near-twin.If it turns out wrong, archive or delete it. A stale fact is worse than none.
Trusting what you read
A recalled memory is background context, not a fresh instruction — it's what was true when it was written.
If it names a file, function or flag: check it still exists before acting on it.
A "not done yet / pending" fact is perishable — re-verify it, don't build on it.
"the user chose X" — was it their independent call, or your suggestion they accepted? Don't misattribute a decision.
Other access methods
Line-delimited JSON bridge
scripts/memcore_bridge.py — one JSON request per line, one JSON response per line.
For local orchestrators (e.g. AgentRoom). No npm, no raw SQLite.
python scripts/memcore_bridge.py --actor codex --origin agentroom --session-ref "room:1/run:42"
# stdin: {"op":"memory_search","query":"deploy steps","limit":5}Raw SQLite — maintenance only
CREATE TABLE entries (
id INTEGER PRIMARY KEY AUTOINCREMENT,
scope TEXT NOT NULL,
type TEXT NOT NULL, -- 'user' | 'feedback' | 'project' | 'reference'
name TEXT NOT NULL, -- slug, unique within its scope
description TEXT NOT NULL DEFAULT '',
content TEXT NOT NULL,
source_path TEXT, -- origin .md path if imported, else NULL
created_at TEXT NOT NULL, -- ISO 8601 UTC
updated_at TEXT NOT NULL,
UNIQUE(scope, name)
);
-- entries_fts (FTS5) is kept in sync by triggers. Never write to it directly.SELECT e.* FROM entries_fts JOIN entries e ON e.id = entries_fts.rowid
WHERE entries_fts MATCH 'your terms' ORDER BY bm25(entries_fts) LIMIT 20;Direct SQL bypasses validation and memory_events — use MCP / CLI / bridge for
anything an agent does; keep raw SQL for human maintenance and restoration.
Markdown import (optional helpers)
scripts/import_md.py and scripts/import_claude_md.py bulk-import an existing
tree of Markdown memory files (the layout Claude Code writes under
.claude/projects/*/memory/) and a CLAUDE.md profile. Both redact common secret
patterns and skip credentials_* files. Re-runnable — they upsert on scope + name.
Conventions
scope— the project or topic (a project name, orglobalfor facts true everywhere). Consistency is nice but not critical: search spans all scopes.name— short kebab-case slug, unique within its scope. Reuse it to update.type—user(who the person is / their preferences),feedback(a lesson or correction they gave),project(a fact/state about ongoing work),reference(a pointer to something external).Store only what should survive the current conversation.
Validation on every write: type must be valid, content non-empty and ≤ 200 000
chars, scope/name/description ≤ 500 chars. Invalid writes return
{"ok": false, "error": "..."} — the store is never corrupted.
Secrets
Two layers:
credentials_*.mdfiles in a Markdown import tree are excluded by filename — never imported.Everything else is redacted, not rejected. On any write, secret-shaped substrings are replaced with
[REDACTED]: private keys (even a truncated paste),ghp_…/github_pat_…,AKIA…,sk-…/sk-ant-…,AIza…,xox[baprs]-…, Telegram bot tokens, JWTs,scheme://user:pass@hostconnection strings,Authorization: Bearer …headers, andpassword:/api_key =lines (a lone value, no path/URL). The surrounding note is kept, the redaction is returned to the caller ("redacted": [codes]) and logged tomemory_events. A note that merely discusses a secret format is fine; a real leaked value is stripped before it hits disk.
If an assistant needs an actual credential, it should ask the user — not look here.
Backup & restore
python scripts/memcore.py backup [--dest PATH] makes a consistent copy (SQLite
backup API — safe even under concurrent writes). Point --dest (or
MEMCORE_BACKUP_PATH) into a folder that is itself backed up.
Restore, worst case first:
DB corrupt, a backup copy exists → stop every tool using MemCore, replace
memcore.dbwith the backup, runmemcore.py healthcheck.No DB, but the source
.mdfiles exist →import_claude_md.pythenimport_md.pyrebuild the index. Lost in this case:memory_history,memory_events, archived entries — the live content of every entry that has a.mdcomes back.DB fine, MCP silent →
memcore.py healthcheck(ifok, it's the MCP layer): fully restart the host, check itsmcpServers.memcoreentry. The CLI works without MCP in the meantime.
Design notes
No daemon. No automatic background capture. No mandatory AI summarization. Just reliable storage + search, plus the guardrails (provenance, concurrency, reversible deletes, access control) that make it safe for several assistants to share one store. Markdown files can live alongside it as the human-readable source of truth; MemCore is a faster, more widely reachable index of them.
Contributing & support
Personal project, maintained in spare time — issues and pull requests are read, but replies may be slow.
Bug → open an issue
Question or idea → Discussions
Security → SECURITY.md (report privately)
Sending a PR → CONTRIBUTING.md
Credits
Designed and written by Claude (Anthropic), directed by Manuel Warland (@ManuelWarland), who maintains it.
License
MIT — Copyright (c) 2026 Manuel Warland.
Available Tools
13 toolsmemory_archiveArchive an entryAIdempotent
Archive (soft-delete) one entry: hide it from normal reads and search while keeping it, restorable with memory_restore and audited in memory_events.
Use it for a fact that became wrong or obsolete; to correct a fact, prefer memory_write on the same scope + name. Nothing is ever physically deleted. Returns {"ok": true} if the entry is now archived (also when it already was), {"ok": false} if no entry has that scope and name, or {"ok": false, "error": ...} when the reason is empty. Not available on read-only connections.
Inputs: name (required), scope (required), reason (required).
memory_embed_statusSemantic search statusARead-onlyIdempotent
Report whether semantic search is active, which embedding model is used, and how many entries have a current vector embedding.
Use it to understand why memory_search finds (or misses) entries that
share no keywords with the query: entries without a current embedding are
lexical-only until they are embedded: usually within 15 s by a read/write
MCP server's background worker, or by the embed-backfill CLI command. For
general counts use memory_stats; to test that the store
works, memory_healthcheck. Read-only, takes no arguments.
Inputs: no named parameters.
memory_eventsAudit logARead-onlyIdempotent
Read the append-only audit log, newest first: who wrote, updated, archived or restored what, when, from which client, and any conflicts or secret redactions.
Use it to answer "who changed this, and why?". To see the previous CONTENT of an entry, use memory_history instead; for the latest entries themselves, memory_recent. Read-only and available on any connection; scope-locked connections only see their own scope's events.
Inputs: name, limit, scope. Returns: result
memory_getGet one entryARead-onlyIdempotent
Fetch one memory entry, complete, by its exact scope and name.
Use it when you already know both keys (from memory_search, memory_list or memory_recent results) and need the full, current content before relying on it. Returns null when no entry has that scope and name, or when it is archived and include_archived is false. Read-only.
Inputs: name (required), scope (required), include_archived. Returns: result
memory_healthcheckSelf-testAIdempotent
Self-test MemCore end to end (about 1 s): write, read, search (strict AND and OR-fallback modes), history and delete.
Use it instead of assuming a connection is healthy just because it is
listed: a connection can look fine while search silently misbehaves.
The test only writes to a throwaway scope (_healthcheck, or
_healthcheck_<scope> on a scope-locked connection) and always cleans
up; real entries are never touched. Returns {ok, checks[], db_path}.
Not available on read-only connections; use memory_stats there.
Inputs: no named parameters.
memory_historyEntry historyARead-onlyIdempotent
Show the prior versions of one entry that were overwritten or deleted, newest first.
Every write that replaces an entry keeps the previous version automatically, so nothing is silently lost even if another agent overwrote it. Use it to recover or compare earlier content. For who made each change use memory_events; for the current version, memory_get. Read-only, available even on a read-only connection. Returns an empty list when the entry has no prior versions.
Inputs: name (required), scope (required), limit. Returns: result
memory_listBrowse entriesARead-onlyIdempotent
Browse entries by scope, type and archived state, WITHOUT a search query.
Use it to see everything in a project scope (onboarding to a codebase),
every entry of one type (e.g. all feedback), or what has been archived
(candidates for memory_restore). To find entries by content use
memory_search; for the latest changes, memory_recent. Read-only. An
invalid type returns [{"error": ...}].
Inputs: type, limit, scope, archived. Returns: result
memory_recentRecently updated entriesARead-onlyIdempotent
List the most recently created or updated memory entries, newest first.
Use it to catch up on what changed lately (start of a session, after another agent worked), optionally within one scope. To find entries by content use memory_search; to browse a scope or type without time ordering use memory_list; for who changed what, use memory_events. Read-only.
Inputs: limit, scope, include_archived. Returns: result
memory_restoreRestore an entryAIdempotent
Restore one archived entry so it appears again in normal reads and search. The inverse of memory_archive.
Find archived entries with memory_list(archived=true). The restore is logged in memory_events with your reason. Returns {"ok": true} if the entry is now active (also when it was not archived), {"ok": false} if no entry has that scope and name, or {"ok": false, "error": ...} when the reason is empty. Not available on read-only connections.
Inputs: name (required), scope (required), reason (required).
memory_scopesList scopesARead-onlyIdempotent
List every known project/topic scope with its number of entries.
Use it first to discover valid scope values for the other tools, or to
see which projects have memory at all. For the total count and the
database location use memory_stats; to browse the entries of one scope,
memory_list. Read-only, takes no arguments. A scope-locked connection
only sees its own scope.
Inputs: no named parameters. Returns: result
memory_searchSearch memoryARead-onlyIdempotent
Search all remembered facts by content, across every project scope.
The default entry point. Use it before assuming something is not known: it searches EVERY scope at once, so there is no need to guess which project a fact was recorded under. Use memory_get instead when you already know the exact scope and name, memory_list to browse without a query, and memory_recent for what changed lately.
Two layers, blended by default:
Lexical (FTS5): multi-word queries first require ALL terms in one entry, then fall back to ANY term (ranked by how many match), so one non-verbatim word doesn't zero the result.
Semantic (if embeddings are present): vector nearest neighbours on a multilingual sentence model, which finds entries about the same idea even with no shared keywords.
Read-only. Archived entries are never returned. Returns a list of entries, best match first; an empty list when nothing matches or the query is invalid.
Inputs: query (required), debug, limit, scope, +1 more.
memory_statsStore statisticsARead-onlyIdempotent
Report the total number of entries, the number of archived entries, the database file location and the list of scopes.
Use it for a quick overview or to check which database file this connection uses. For per-scope counts use memory_scopes; for semantic search coverage, memory_embed_status; to verify the store actually works, memory_healthcheck. Read-only, takes no arguments.
Inputs: no named parameters.
memory_writeWrite an entryA
Record a new fact, or update an existing one (same scope + name updates it in place).
Search first (memory_search) to avoid creating a duplicate under a
different name. An update keeps the previous version in
memory_history and is logged in memory_events, so it can be undone.
Updating an archived entry is refused: restore it first with
memory_restore. Secret-shaped values in content (API keys, tokens,
password: ... lines) are replaced by [REDACTED] before storage; if
any were, the result includes "redacted": [<codes>].
Returns {"ok": true, "id": ...} on success, or {"ok": false, "error": ...} for an invalid argument, a conflict (stale expected_updated_at or archived entry) or a busy database (retry). Not available on read-only connections.
Inputs: name (required), type (required), scope (required), content (required), +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool targets a distinct axis: content search, exact-key fetch, browsing by scope/type, time-ordered recents, audit events, version history, semantic status, healthcheck, and lifecycle mutations. The descriptions explicitly cross-reference nearby tools and state when to use one instead of another, so an agent can reliably select the right tool.
All names use the consistent `memory_` prefix and snake_case, making the family easy to scan. However, suffixes mix verbs (`search`, `get`, `write`, `archive`) with nouns/adjectives (`stats`, `recent`, `events`, `scopes`, `history`, `healthcheck`), so the verb_noun pattern is not fully uniform.
Thirteen tools is well within the appropriate range for a memory store with search, scopes, audit history, versioning, archive/restore, and health checks. Each tool earns its place by covering a distinct operation rather than duplicating functionality.
The lifecycle is fully covered: create/update via `memory_write`, read via search/get/list/recent, soft-delete via archive, restore, audit events, prior-version history, scope discovery, stats, semantic embedding status, and end-to-end healthcheck. The absence of hard delete is intentional and explained, not a dead end.
Maintenance
Related MCP Connectors
Shared memory for coding agents. Stop re-explaining your codebase every session.
Persistent memory for AI agents: one brain shared across Claude, Cursor, Codex and more.
Long-term memory for AI assistants: permanent, portable across clients, searchable and exportable.
Shared memory for AI coding agents. Save once, reuse from Cursor, Claude Code, Codex.
Related MCP Servers
- AlicenseAqualityAmaintenancePersistent AI memory with SQLite hybrid search (FTS5 + semantic), built-in Qwen3 embedding, and rclone sync across machines.15307 PyPI13Apache 2.0
- AlicenseAqualityDmaintenanceProvides persistent cross-session memory and full-text search for AI coding assistants, storing project context, decisions, and preferences while enabling searchable access to conversation history via local SQLite.81MIT
- AlicenseNot gradedqualityCmaintenanceProvides long-term memory for LLMs via local SQLite storage with hybrid search (BM25, vectors, recency decay), enabling AI coding agents to persist and recall memories across sessions without cloud or API keys.52MIT
- AlicenseNot gradedqualityDmaintenancePersistent memory for AI coding agents with local-first, zero-cost, privacy-first SQLite/FTS5 storage and biological-inspired decay.17 npm3MIT