agent-memory MCP server
Commit Oct 25, 2026Provides persistent, typed, and cross-runtime memory for AI agents using a local SQLite database.
Also known as UnityInFlow/agent-memory
- Stars
- 0
- Tools
- 17
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 25, 2026
- License
- MIT
What is agent-memory MCP?
agent-memory provides persistent, typed, and cross-runtime memory for AI agents using a local SQLite database. It exposes 17 tools, such as memory_store, memory_search, memory_list.
Summary generated from the project's README
About agent-memory MCP server
Giving AI agents a way to remember information across different sessions and tools is what agent-memory achieves. It provides a persistent, local, and offline storage system using an embedded SQLite database, ensuring that your data never leaves your machine. By pointing multiple MCP runtimes to the same database file via the AGENT_MEMORY_DB environment variable, different agents can share a single collective memory.
Developers can organize information into six specific categories: DECISION, PATTERN, ERROR, TODO, ARCHITECTURE, and CONSTRAINT. This structured approach allows for more precise retrieval than a simple text dump. The server supports hybrid search, combining keyword matching with semantic search if a local Ollama instance is available for embeddings. If Ollama is not present, it automatically falls back to SQLite FTS5 keyword ranking. Memories are managed through a decay system where importance fades over time rather than being immediately deleted, though users can still use memory_forget or set a TTL for explicit removal.
What you can do with it
- 1Maintain cross-session contextAn AI agent can store a specific architectural decision so that a completely different agent can recall it in a later session.
- 2Organize agent knowledge by typeA developer can instruct an agent to categorize a new task as a TODO or a technical constraint to make it easier to find later.
- 3Manage memory lifespanAn agent can be told to forget a specific piece of information after a certain amount of time has passed.
Written from the project's README. Every use case is checked against a quote from it.
agent-memory MCP tools 17
Detected from the READMEmemory_storememory_searchmemory_listmemory_updatememory_linkmemory_unlinkmemory_forgetsearch_modecontenttagsscopettl_secs
| memory_store | — | |
| memory_search | — | |
| memory_list | — | |
| memory_update | — | |
| memory_link | — | |
| memory_unlink | — | |
| memory_forget | — | |
| search_mode | — | |
| content | — | |
| tags | — | |
| scope | — | |
| ttl_secs | — |
Show all 17 toolsShow fewer tools
kindrelates_tosupersedescaused_bylimit
| kind | — | |
| relates_to | — | |
| supersedes | — | |
| caused_by | — | |
| limit | — |
Configuration
AGENT_MEMORY_DBAGENT_MEMORY_OLLAMA_URL
| Name | Description | |
|---|---|---|
| AGENT_MEMORY_DB | — | |
| AGENT_MEMORY_OLLAMA_URL | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableunityinflow/agent-memory is public and reachablegithub.com/unityinflow/agent-memory ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-25github.com/unityinflow/agent-memory ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model17 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubagent-memory
Persistent, cross-runtime, typed memory for AI agents — local, offline, no cloud.
Tool 10 in the UnityInFlow ecosystem.
- crates.io:
agent-memory-mcp(installs theagent-memoryexecutable) - MCP Registry name:
mcp-name: io.github.UnityInFlow/agent-memory
AI agents forget everything between sessions. agent-memory is a small
MCP stdio server backed by an embedded SQLite
database: any MCP-speaking runtime can store, search, list, update, and forget
structured memories, and every runtime pointed at the same database file shares the same
memory — so a decision recorded by one agent is recalled by the next, across
sessions and across tools.
- Local & offline. Embedded SQLite, zero accounts, zero cloud. Your memory never leaves your machine.
- Typed memories. Six categories —
DECISION,PATTERN,ERROR,TODO,ARCHITECTURE,CONSTRAINT— so retrieval is structured, not a soup of text. - Decay, not deletion. Memories fade in ranking over time (exponential decay;
high-value pinned types fade slower) but are never deleted by decay. The only
ways a memory is removed are an explicit TTL expiry or
memory_forget. - Search by meaning and by keyword. Hybrid search when local Ollama embeddings are available: a keyword ranking and a semantic ranking are fused, so an exact-term hit and a paraphrase both surface. Automatic fallback to SQLite FTS5 keyword ranking when Ollama isn't there, and both modes are blended with decay. No Ollama, no network? Everything still works.
Install
Homebrew (macOS + Linux)
brew install unityinflow/tap/agent-memory
Pre-built binaries
Download the tarball for your platform from the latest release:
| Platform | Asset |
|---|---|
| macOS arm64 (Apple Silicon) | agent-memory-aarch64-apple-darwin.tar.gz |
| macOS x86_64 (Intel) | agent-memory-x86_64-apple-darwin.tar.gz |
| Linux x86_64 (gnu) | agent-memory-x86_64-unknown-linux-gnu.tar.gz |
| Linux aarch64 (gnu) | agent-memory-aarch64-unknown-linux-gnu.tar.gz |
| Linux x86_64 (musl, static) | agent-memory-x86_64-unknown-linux-musl.tar.gz (when available) |
| Linux aarch64 (musl, static) | agent-memory-aarch64-unknown-linux-musl.tar.gz (when available) |
Verify the checksum against SHA256SUMS.txt (shipped with every release),
then extract:
shasum -a 256 -c SHA256SUMS.txt --ignore-missing # (sha256sum on Linux)
tar -xzf agent-memory-<triple>.tar.gz
./agent-memory --version
From crates.io
Requires a stable Rust toolchain. The crate is agent-memory-mcp (the name
agent-memory on crates.io belongs to an unrelated project); the executable it
installs is still agent-memory:
cargo install agent-memory-mcp --locked
agent-memory --version
From source
Requires a stable Rust toolchain (edition 2021).
git clone https://github.com/UnityInFlow/agent-memory
cd agent-memory
cargo build --release
# binary at target/release/agent-memory
Run
# Serve the MCP stdio server (creates the DB on first run).
agent-memory serve
# Choose the database file (default: your OS data dir; honors $AGENT_MEMORY_DB).
agent-memory --db /path/to/memory.db serve
AGENT_MEMORY_DB=/path/to/memory.db agent-memory serve
# Move the memory elsewhere.
agent-memory export --output memories.jsonl # portable JSONL export (see Export & import)
The server speaks JSON-RPC over stdout; all logs go to stderr, so stdout stays a pure protocol channel.
Upgrading
A new agent-memory version may need to migrate the database schema. It does this automatically the first time it opens the file, and backs the database up first.
- Pre-migration backup. Before any schema migration, the database is copied
with SQLite's online backup to
memory.db.backup-pre-NNNN-YYYYMMDD, next tomemory.db.NNNNis the schema version being migrated to andYYYYMMDDis the UTC date. A brand-new database has nothing to back up. - One backup per target schema version. Re-running the same upgrade replaces that version's backup atomically. The new copy is written to a temporary file, renamed into place, and only then is the older copy removed. Backups made for other schema versions are never touched.
- No backup, no migration. If the backup cannot be written (for example a full disk or a read-only directory), the server refuses to start and the database is not migrated.
- Starting several servers at once is safe. If an MCP server and the REST daemon open an older database at the same moment, both start. The schema is migrated once, and the surviving backup is always a genuine pre-migration copy.
Restoring a backup:
- Stop every agent-memory process that uses the database: each MCP server and the REST daemon.
- Copy the backup over the database:
cp memory.db.backup-pre-0003-20261023 memory.db. - Delete
memory.db-walandmemory.db-shmif they exist. They belong to the database you replaced. - Start the older agent-memory binary that matches the backup's schema.
A newer database meets an older binary. A database written by a newer agent-memory is refused at startup, and the file is left untouched. The error names both schema versions:
database schema is version 4 but this binary supports up to version 3 — upgrade agent-memory (brew upgrade unityinflow/tap/agent-memory) or point --db at a different file
MCP configuration (.mcp.json)
Point every runtime at one database via AGENT_MEMORY_DB and they share memory:
{
"mcpServers": {
"agent-memory": {
"command": "agent-memory",
"args": ["serve"],
"env": {
"AGENT_MEMORY_DB": "/Users/you/.agent-memory/memory.db"
}
}
}
}
Drop the same block into each agent runtime's MCP config; because they open the
same AGENT_MEMORY_DB file (WAL-mode SQLite with a serialized writer), a memory
stored in one is immediately retrievable in another.
The seven tools
| Tool | Purpose | Validated parameters |
|---|---|---|
memory_store |
Persist a typed memory; returns its id. | ttl_secs: optional integer, valid range 1–3155760000 (~100 years); omitted = no expiry |
memory_search |
Hybrid (keyword + semantic, rank-fused) search when Ollama is reachable, FTS5 keyword otherwise — weighted by decay, and only the returned results are recency-bumped. Accepts plain natural-language queries (any punctuation) as well as FTS5 syntax. | limit: optional integer, valid range 1–200; omitted defaults to 50. tag: exact tag match (case-sensitive). expand_links: optional boolean, default false |
memory_list |
List memories newest-first, with optional type/tag/scope filters. | limit: optional integer, valid range 1–200; omitted = unlimited, required when expand_links is true. tag: exact tag match (case-sensitive). expand_links: optional boolean, default false |
memory_update |
Patch a memory in place by id — content, tags, scope, TTL (clean not-found for unknown ids). | content: never null or empty. ttl_secs: 1–3155760000 when set; null = no expiry. At least one field besides id |
memory_link |
Link two memories with a typed, directed relation (idempotent; clean not-found for unknown ids). | kind: one of relates_to, supersedes, caused_by. from_id ≠ to_id |
memory_unlink |
Remove a relation (clean not-found when no such edge exists). | kind: one of relates_to, supersedes, caused_by |
memory_forget |
Delete a memory by id (clean not-found for unknown ids). Its relations go with it. | — |
Out-of-bounds values are rejected as client errors (invalid_params over MCP)
with a message naming the field, the valid range, and the offending value —
e.g. invalid argument: limit must be between 1 and 200 (got 0). They are
never silently clamped and never produce an internal error.
memory_store
{
"content": "We chose io.github.unityinflow as the Maven group.",
"type": "DECISION",
"tags": ["maven", "release"],
"scope": "kore-runtime",
"ttl_secs": null
}
content and type are required; tags, source, scope, and ttl_secs are
optional. A non-null ttl_secs makes the memory expire that many seconds after it
is stored — the background sweep then removes it. A present ttl_secs must be
between 1 and 3155760000 (~100 years); anything else is rejected with the range
in the error message.
memory_search
{ "query": "maven group", "type": "DECISION", "limit": 10 }
Returns an envelope carrying the mode actually used plus the ranked results,
each with a freshly-recomputed decay_score:
{ "search_mode": "hybrid", "results": [ ... ] }
search_mode |
When | How results are ranked |
|---|---|---|
"hybrid" |
Ollama is reachable | Two rankings are fused with Reciprocal Rank Fusion: the semantic (embedding KNN) ranking and the keyword (FTS5 bm25) ranking, each oversampled to 4 × limit. A memory at rank r in a ranking scores 1 / (60 + r) (k = 60), and a memory found by both rankings sums both scores, so agreement wins: 2nd in both beats 1st in one. The fused score is then multiplied by the memory's decay score, once, so at equal fused rank the fresher memory wins and pinned types keep their slower fade. |
"keyword" |
Ollama is absent or unreachable | FTS5 bm25 relevance blended with decay — the v0.0.1 path, unchanged. |
The envelope is the same {search_mode, results} shape in both modes. A query
that matches nothing returns an empty list, never an error, and an empty hybrid
answer is still reported as "hybrid". A present limit must be between 1 and
200 (omitted defaults to 50); a tag filter matches whole tags exactly and
case-sensitively.
- Plain language or FTS5 syntax — a query is never rejected. The raw query
runs through FTS5 first, so valid FTS5 expressions (
sqlite AND vec,"exact phrase",vec*) keep their exact meaning. A query FTS5 cannot parse — a question mark, a comma or apostrophe, a hyphen or colon (sqlite-vec,TODO: auth), an unbalanced"— is retried once with its words quoted and OR-ed together, sowhat vector store do we use?searches forwhat,vector,store, … A query with no words at all (empty,?!,*) contributes no keyword matches: hybrid answers from the semantic ranking alone and keyword mode returns an empty list. This holds identically in both modes, so whether Ollama is up never changes how a query is treated. - Only returned results are recency-bumped. The candidates fusion looked at
but did not return, and any
expand_linksneighbors, are not touched, so a search never changes how unseen memories decay. - Filters and the semantic ranking. The semantic ranking applies
type/tag/scopefilters after its 4 ×limitcandidate cut, so a heavily filtered hybrid query can recall fewer thanlimitresults. The keyword ranking filters before its cut.
memory_list
{ "type": "TODO", "scope": "kore-runtime", "limit": 20 }
A present limit must be between 1 and 200 (omitted returns everything,
except that expand_links: true requires a limit); a tag filter matches
an exact tag (case-sensitive).
Both memory_search and memory_list accept "expand_links": true to attach
each result's linked memories — see Relations.
memory_forget
{ "id": 42 }
Returns { "id": 42, "deleted": true }, or deleted: false for an unknown id.
memory_update
Patch an existing memory in place — its id never changes. The arguments
are a JSON merge-patch: each field you send is applied, each field you omit is
left alone, and an explicit null clears the field where clearing is legal.
{ "id": 42, "content": "We chose io.github.unityinflow as the Maven group (Sonatype-verified).", "ttl_secs": null }
| Field | Omitted | null |
A value |
|---|---|---|---|
content |
unchanged | rejected (invalid_params) |
replaced, then re-indexed and re-embedded |
tags |
unchanged | cleared to [] |
replaced (the whole list) |
scope |
unchanged | reset to global (null) |
replaced |
ttl_secs |
unchanged (the existing expiry stays) | expiry removed — the memory never expires | a new TTL counted from now (1–3155760000) |
type and source cannot be changed; to retype a memory, store a new one and
forget the old. A patch with no field besides id, empty or whitespace-only
content, or an out-of-bounds ttl_secs is rejected as invalid_params
before anything is written.
Unknown fields are rejected too, never silently ignored: a patch carrying
type, source or a misspelled field such as ttl_sec fails as a whole and
writes nothing. Over MCP it is a tool error result (isError: true) whose text
reads failed to deserialize parameters: unknown field ... and names the
field; over REST it is HTTP 400 with the same message in the error body.
On success the result is the full updated memory — the same fields memory_list
returns — plus embedding_status:
{ "id": 42, "content": "We chose io.github.unityinflow as the Maven group (Sonatype-verified).",
"type": "DECISION", "tags": ["maven", "release"], "scope": "kore-runtime",
"decay_score": 1.0, "created_at": 1767225600, "last_accessed": 1767312000,
"embedding_status": 1 }
- New content changes the meaning, everywhere. The keyword index and the embedding are replaced in the same transaction, so a search for the old meaning stops matching the memory and the new meaning finds it.
embedding_statusis1when the stored vector matches the current content and0when a re-embed is pending — the update succeeded while Ollama was unreachable, and the background sweep re-embeds it once Ollama is back. Until then the semantic ranking cannot match it by meaning; the keyword ranking (in hybrid and keyword mode alike) already sees the new content.- An update counts as a use. It refreshes
last_accessed(and the access count), so an edited memory ranks as current rather than decayed. - Expired but not yet swept still counts as present. An update to a memory
whose TTL has already passed, but which the background sweep
has not yet removed, still succeeds, just as
memory_listandmemory_searchstill show it until the sweep runs. Attl_secspatch can extend or clear its expiry.
For an unknown id the result is { "id": 42, "updated": false, "reason": "not_found" }
— a normal tool result, not an error.
Relations (memory_link / memory_unlink)
Connect memories with flat, typed relations — no graph model, just one edge
from_id -[kind]-> to_id per relation:
kind |
Reads as | Seen from to_id (expansion) |
|---|---|---|
relates_to |
from_id relates to to_id (symmetric "see also") |
relates_to |
supersedes |
from_id replaces the older to_id |
superseded_by |
caused_by |
from_id was caused by to_id |
caused |
{ "from_id": 57, "to_id": 42, "kind": "supersedes" }
memory_link returns { "from_id": 57, "to_id": 42, "kind": "supersedes", "linked": true }.
- Idempotent. Linking the same
(from_id, to_id, kind)again is a no-op success — safe to retry. A differentkindbetween the same pair is a separate relation.relates_tois symmetric, so linkingb → aaftera → bis the same relation and also a no-op success.supersedesandcaused_byare directed:a → bandb → aare two relations. - Responses echo your request.
memory_link/memory_unlink(and the REST link bodies) always report thefrom_idandto_idyou sent, even though arelates_torelation is stored as (smaller id, larger id). - Rejected as
invalid_params: a self-link (from_id and to_id must differ (got 57)) and an unknown kind (kind must be one of relates_to, supersedes, caused_by (got 'blocks')). - Unknown ids are a clean not-found:
{ ..., "linked": false, "reason": "not_found", "missing_id": 42 }names the id that does not exist. Nothing is written.
memory_unlink takes the same three fields. For supersedes and caused_by,
direction and kind must match the stored edge; a relates_to relation is
symmetric and can be removed from either end. It returns "unlinked": true,
or "unlinked": false, "reason": "not_found" when no such edge exists.
Relations never outlive their memories. Forgetting a memory, or its TTL expiring, removes every relation touching it in the same transaction.
Expansion. Pass "expand_links": true to memory_search or
memory_list and every result gains a related list of trimmed 1-hop
summaries, following relations in both directions:
{ "id": 42, "content": "...", "type": "DECISION", "...": "...",
"related": [
{ "id": 57, "kind": "superseded_by", "direction": "in",
"type": "DECISION", "snippet": "Maven group is io.github.unityinflow (Sonatype-verified).", "tags": ["maven"] }
] }
directionisoutwhen the result is the relation'sfrom_idandinwhen it is theto_id;kindreads naturally from the result's side (the table above). Forrelates_tothe reporteddirectioncarries no meaning: the relation is symmetric and stored with the smaller id first.snippetis the neighbor's content cut to 160 characters, with a trailing…when cut. Fetch the neighbor by id if you need all of it. The cut counts characters, not visual glyphs, so it may split a combined emoji or accent sequence.- At most
MAX_EXPANDED_LINKS = 10neighbors per result; when a memory has more, the most recently created relations win. memory_listwithexpand_linksrequires alimit(1–200). Without one the call is rejected as a client error (HTTP 400 / MCPinvalid_params) whose message tells you to pass alimit, so an expanded response is always bounded at 200 results × 10 neighbors.memory_searchis bounded by its ownlimit(default 50). Withoutexpand_links, an omittedlimitstill lists every memory.- Expansion is strictly one hop and a pure read: neighbors are not recency-bumped, so expanding never changes how anything decays.
- A result with no relations gets
"related": []. Without the flag there is norelatedmember at all — the response is exactly the v0.0.1 shape.
Bounds
| Bound | Value | Applies to |
|---|---|---|
limit |
1–200 (MAX_LIMIT) |
memory_search (default 50), memory_list (default unlimited; required with expand_links) |
ttl_secs |
1–3155760000 (~100 years) | memory_store, memory_update |
MAX_EXPANDED_LINKS |
10 neighbors per result, most recent first | expand_links on search and list |
| snippet length | 160 characters (+ … when cut) |
related[].snippet |
Semantic search (optional Ollama)
Out of the box, search uses SQLite FTS5 keyword ranking — fully offline, no extra software. To rank by meaning instead, run a local Ollama and pull the embedding model:
ollama pull nomic-embed-text
That's the whole setup. When Ollama is reachable, stores embed content
automatically and searches run in hybrid mode: vector KNN (cosine) and FTS5
keyword rankings fused with RRF, then weighted by decay
(see memory_search). Point
at a non-default Ollama with either:
agent-memory --ollama-url http://localhost:11434 serve
AGENT_MEMORY_OLLAMA_URL=http://localhost:11434 agent-memory serve
Graceful fallback, always. If Ollama is stopped, absent, or the model isn't pulled:
- stores still succeed — content is queued (
embedding_status = 0) and backfilled by the background sweep once Ollama returns; - searches transparently fall back to the FTS5 keyword path and report it via
"search_mode": "keyword"— the same envelope and the same ranking as v0.0.1; - nothing errors, nothing blocks. The tool works fully offline without Ollama.
agent-memory MCP questions
What tools does agent-memory MCP provide?
It exposes 17 tools, including memory_store, memory_search, memory_list, memory_update, memory_link.
Is my data stored in the cloud?
No, the server is local and offline. Your memory never leaves your machine because it uses an embedded SQLite database.
Can different AI agents share the same memory?
Yes, any MCP-speaking runtime pointed at the same database file shares the same memory, allowing decisions recorded by one agent to be recalled by another.
How does the search function work if I don't have Ollama?
If Ollama is unavailable, the server automatically falls back to SQLite FTS5 keyword ranking.
Are memories permanently deleted when they decay?
No, memories only fade in ranking over time due to exponential decay; they are only removed via explicit TTL expiry or a manual forget command.