agent-memory MCP server
2026년 10월 25일 커밋로컬 SQLite 데이터베이스를 사용하여 AI agent에게 지속적이고 타입이 지정된 교차 런타임 메모리를 제공합니다.
다른 이름 UnityInFlow/agent-memory
- 스타
- 0
- Tools
- 17
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 10월 25일
- 라이선스
- MIT
agent-memory MCP란?
로컬 SQLite 데이터베이스를 사용하여 AI agent에게 지속적이고 타입이 지정된 교차 런타임 메모리를 제공합니다. 17개 도구를 제공합니다. 예: memory_store, memory_search, memory_list.
프로젝트 README에서 생성된 요약
agent-memory MCP server 정보
agent-memory는 AI agent가 서로 다른 세션과 도구 사이에서 정보를 기억할 수 있는 방법을 제공합니다. 임베디드 SQLite 데이터베이스를 사용하여 지속적이고 로컬이며 오프라인인 저장 시스템을 제공하므로 데이터가 사용자의 기지를 벗어나지 않도록 보장합니다. AGENT_MEMORY_DB 환경 변수를 통해 여러 MCP 런타임을 동일한 데이터베이스 파일로 지정하면 서로 다른 agent가 하나의 공동 메모리를 공유할 수 있습니다.
개발자는 정보를 DECISION, PATTERN, ERROR, TODO, ARCHITECTURE, CONSTRAINT의 6가지 특정 카테고리로 정리할 수 있습니다. 이러한 구조적 접근 방식은 단순한 텍스트 저장보다 더 정밀한 검색을 가능하게 합니다. 이 서버는 키워드 매칭과 임베딩을 위한 로컬 Ollama 인스턴스가 있는 경우 시맨틱 검색을 결합한 하이브리드 검색을 지원합니다. Ollama가 없는 경우 자동으로 SQLite FTS5 키워드 랭킹 방식으로 전환됩니다. 메모리는 즉시 삭제되는 대신 시간이 지남에 따라 중요도가 낮아지는 감쇠 시스템을 통해 관리되지만, 사용자는 memory_forget을 사용하거나 TTL을 설정하여 명시적으로 삭제할 수 있습니다.
활용 사례
- 1교차 세션 컨텍스트 유지AI agent가 특정 아키텍처 결정을 저장하면, 완전히 다른 agent가 나중에 해당 세션에서 이를 회상할 수 있습니다.
- 2유형별 agent 지식 정리개발자는 agent에게 새로운 작업을 TODO 또는 기술적 제약 사항으로 분류하도록 지시하여 나중에 더 쉽게 찾을 수 있도록 할 수 있습니다.
- 3메모리 수명 관리특정 정보가 일정 시간이 지난 후에 잊혀지도록 agent에게 지시할 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
agent-memory MCP 도구 17
README에서 감지됨memory_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 | — |
도구 17개 모두 보기도구 수 줄이기
kindrelates_tosupersedescaused_bylimit
| kind | — | |
| relates_to | — | |
| supersedes | — | |
| caused_by | — | |
| limit | — |
구성
AGENT_MEMORY_DBAGENT_MEMORY_OLLAMA_URL
| 이름 | 설명 | 유형 |
|---|---|---|
| AGENT_MEMORY_DB | — | |
| AGENT_MEMORY_OLLAMA_URL | — |
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능unityinflow/agent-memory is public and reachablegithub.com/unityinflow/agent-memory ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-10-25github.com/unityinflow/agent-memory ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음17 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨No tool named like delete, drop or exec통과
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기agent-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 질문
agent-memory MCP는 어떤 도구를 제공하나요?
17개 도구를 제공합니다. 예: memory_store, memory_search, memory_list, memory_update, memory_link.
데이터가 클라우드에 저장되나요?
아니요, 서버는 로컬에서 오프라인으로 작동합니다. 임베디드 SQLite 데이터베이스를 사용하므로 메모리는 사용자의 기기를 절대 벗어나지 않습니다.
서로 다른 AI agent가 동일한 메모리를 공유할 수 있나요?
네, 동일한 데이터베이스 파일을 가리키는 MCP 지원 런타임이라면 무엇이든 메모리를 공유할 수 있습니다. 이를 통해 한 agent가 기록한 결정을 다른 agent가 회상할 수 있습니다.
Ollama가 없는 경우 검색 기능은 어떻게 작동하나요?
Ollama를 사용할 수 없는 경우, 서버는 자동으로 SQLite FTS5 키워드 랭킹 방식으로 전환됩니다.
메모리가 노후화되면 영구적으로 삭제되나요?
아니요, 메모리는 지수적 감쇠(exponential decay)에 따라 시간이 지남에 따라 순위가 낮아질 뿐입니다. 명시적인 TTL 만료나 수동 forget 명령을 통해서만 삭제됩니다.