SQLite와 시맨틱 검색을 활용하여 AI 어시스턴트에게 로컬 우선 방식의 그래프 메모리를 제공하며, 이를 통해 장기적인 컨텍스트를 회상하고 연결하며 학습할 수 있습니다.
다른 이름 SimoneB79/memory-engine-mcp, memory-engine-mcp
- 스타
- 1
- Tools
- 36
- 다운로드, 30일
- —
- 최신 버전
- 1.5.3
- 마지막 커밋
- 2026년 10월 22일
- 라이선스
- MIT
Memory Engine MCP란?
SQLite와 시맨틱 검색을 활용하여 AI 어시스턴트에게 로컬 우선 방식의 그래프 메모리를 제공하며, 이를 통해 장기적인 컨텍스트를 회상하고 연결하며 학습할 수 있습니다. 36개 도구를 제공합니다. 예: remember, recall, working_set.
프로젝트 README에서 생성된 요약
Memory Engine MCP server 정보
Memory Engine MCP는 로컬 우선 그래프 메모리 시스템을 통해 AI 어시스턴트에게 장기적인 연속성을 제공합니다. 개발자는 SQLite와 시맨틱 검색을 결합하여 Claude Desktop, Cursor 또는 Windsurf와 같은 에이전트가 과거의 상호작용을 회상하고, 연결하고, 학습할 수 있는 능력을 부여할 수 있습니다. 정보를 타입화된 본드(bond)로 연결된 타입화된 원자(atom)로 모델링함으로써, 이 시스템은 단순한 키-값 저장소를 넘어 구조화된 지식 그래프를 생성합니다.
사용자는 Docker 또는 로컬 Python 환경을 통해 이 MCP server를 배포할 수 있으며, SSE 또는 stdio를 통해 MCP 클라이언트에 연결할 수 있습니다. 시스템은 전체 텍스트 검색을 위해 SQLite FTS5를 활용하며, 의미 기반 검색을 위해 nomic-embed-text 모델을 사용하는 로컬 Ollama 임베딩과 통합할 수 있습니다. 또한 유지보수를 위한 curator_run이나 실수를 기록하는 error_log와 같이 메모리 상태를 관리하기 위한 특화된 도구를 포함합니다. 이러한 설정을 통해 클라우드 기반 API 키 없이도 감쇠 주기(decay cycles)와 자동 중복 탐지를 통해 컨텍스트의 관련성을 유지할 수 있습니다.
활용 사례
- 1장기적인 프로젝트 컨텍스트 유지AI 어시스턴트에게 이전 세션에서 다루었던 특정 아키텍처 결정 사항이나 프로젝트 사실을 찾아달라고 요청하세요.
- 2지식을 그래프 형태로 조직화어시스턴트가 서로 다른 정보들 사이에 관계를 생성하여 구조화된 지식 베이스를 구축하도록 하세요.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
Memory Engine MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 Memory Engine MCP 설치
$ claude mcp add memory-engine-mcp -- docker run -i --rm ghcr.io/simoneb79/memory-engine-mcp:1.5.3Cursor에 Memory Engine MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"memory-engine-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/simoneb79/memory-engine-mcp:1.5.3"
]
}
}
}VS Code에 Memory Engine MCP 설치
.vscode/mcp.json
{
"servers": {
"memory-engine-mcp": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/simoneb79/memory-engine-mcp:1.5.3"
]
}
}
}VS Code CLI에 Memory Engine MCP 설치
$ code --add-mcp '{"name":"memory-engine-mcp","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/simoneb79/memory-engine-mcp:1.5.3"]}'Claude Desktop에 Memory Engine MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"memory-engine-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/simoneb79/memory-engine-mcp:1.5.3"
]
}
}
}Codex에 Memory Engine MCP 설치
$ codex mcp add memory-engine-mcp -- docker run -i --rm ghcr.io/simoneb79/memory-engine-mcp:1.5.3Codex config.toml에 Memory Engine MCP 설치
~/.codex/config.toml
[mcp_servers.memory-engine-mcp] command = "docker" args = ["run", "-i", "--rm", "ghcr.io/simoneb79/memory-engine-mcp:1.5.3"]
Gemini CLI에 Memory Engine MCP 설치
$ gemini mcp add -s user memory-engine-mcp docker -- run -i --rm ghcr.io/simoneb79/memory-engine-mcp:1.5.3Gemini settings.json에 Memory Engine MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"memory-engine-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/simoneb79/memory-engine-mcp:1.5.3"
]
}
}
}Memory Engine MCP 도구 36
README에서 감지됨rememberrecallworking_setsemantic_searchget_atomlist_atomsmerge_atomsexport_atomsearch_graphsuggest_bondssuggest_bonds_allcurator_run
| remember | — | |
| recall | — | |
| working_set | — | |
| semantic_search | — | |
| get_atom | — | |
| list_atoms | — | |
| merge_atoms | — | |
| export_atom | — | |
| search_graph | — | |
| suggest_bonds | — | |
| suggest_bonds_all | — | |
| curator_run | — |
도구 36개 모두 보기도구 수 줄이기
cognitive_statuslearning_rundecay_runcleanup_sessionscleanup_duplicatesreindex_embeddingserror_checkerror_logerror_listpreference_searchimport_markdownmemory_summarystatsversionrecall_sessionsession_summarymemory_contradictlist_contradictionsclassify_memory_tiermemory_impactbackup_databaserestore_databaseexport_allimport_data
| cognitive_status | — | |
| learning_run | — | |
| decay_run | — | |
| cleanup_sessions | — | |
| cleanup_duplicates | — | |
| reindex_embeddings | — | |
| error_check | — | |
| error_log | — | |
| error_list | — | |
| preference_search | — | |
| import_markdown | — | |
| memory_summary | — | |
| stats | — | |
| version | — | |
| recall_session | — | |
| session_summary | — | |
| memory_contradict | — | |
| list_contradictions | — | |
| classify_memory_tier | — | |
| memory_impact | — | |
| backup_database | — | |
| restore_database | — | |
| export_all | — | |
| import_data | — |
구성
MARKDOWN_SOURCEOptional directory for one-way markdown import.
MEMORY_API_TOKENMEMORY_DB_PATHSQLite database path inside the container.
MEMORY_PORTSSE server port. Default: 8085.
| 이름 | 설명 | 유형 |
|---|---|---|
| MARKDOWN_SOURCE | Optional directory for one-way markdown import. | |
| MEMORY_API_TOKEN | — | |
| MEMORY_DB_PATH | SQLite database path inside the container. | |
| MEMORY_PORT | SSE server port. Default: 8085. |
자동 검사
2026년 11월 12일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능통과
- 오픈 소스 라이선스 (OSI)통과
- 최근 1년 내 커밋 또는 릴리스통과
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 원격 엔드포인트가 HTTPS 사용검사되지 않음
- 파괴적인 도구에 라벨 표시됨통과
- 모델에 대한 숨겨진 지침 없음통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
README
GitHub에서 보기Why Memory Engine?
Most MCP memory servers are either simple key-value stores or plain text search wrappers.
Memory Engine is different: it models memory as typed atoms connected by typed bonds, then retrieves context with a hybrid ranking pipeline that combines:
- full-text search (SQLite FTS5)
- semantic similarity via local Ollama embeddings
- confidence, recency, and weight
- graph expansion from related memories
The goal is not just storage. The goal is a memory system that can recall, connect, decay, curate, and learn over time.
Highlights
- Local-first — SQLite database, optional local embeddings via Ollama, no required cloud API.
- MCP-native — exposes 35 tools through FastMCP.
- Graph-aware recall — expands top hits through bidirectional bonds for richer context.
- Semantic search — meaning-based retrieval with
nomic-embed-text. - Markdown coexistence — import existing notes one-way without replacing your human-readable memory.
- Error memory — remembers mistakes and corrections, with auto-promotion to preferences after repeated failures.
- Cognitive curator — non-destructive maintenance pass for compaction, bond suggestions, duplicate detection, and isolated atom classification.
- Session watcher — canonical OpenClaw SQLite ingestion (schema 17), reset-aware digests, and JSONL legacy fallback.
- Backup & restore — full SQLite snapshots, JSON export/import, verified restores with automatic safety backups.
- Auth & hardening — optional API token, secure bind, input validation, rate limiting.
- Test suite — 144 tests covering CRUD, ranking, migrations, auth, backup, concurrency, and transcript ingestion.
- Benchmark — CLI recall quality suite with Precision@K, MRR, latency percentiles.
Architecture
AI assistant / MCP client
│
▼
FastMCP server — 35 tools
│
▼
Memory engine — hybrid ranking, graph recall, decay, learning
│
├── SQLite — atoms, bonds, FTS5, JSON metadata, versions
├── Ollama — optional local embeddings
├── Curator — conservative maintenance
└── Session watcher — OpenClaw SQLite + JSONL fallback
MCP Tools
Memory
| Tool | Purpose |
|---|---|
remember |
Create or update an atom |
recall |
Smart hybrid recall with graph expansion |
working_set |
Build a task-oriented context pack |
semantic_search |
Pure semantic search |
get_atom |
Read one atom with bonds |
list_atoms |
Browse atoms by domain/type/status |
merge_atoms |
Merge duplicate atoms |
export_atom |
Export one atom as markdown |
Knowledge graph
| Tool | Purpose |
|---|---|
link / unlink |
Create or remove typed bonds |
search_graph |
Traverse the graph from one atom |
suggest_bonds |
Suggest bonds for one atom |
suggest_bonds_all |
Suggest or create bonds in bulk |
Learning and maintenance
| Tool | Purpose |
|---|---|
curator_run |
Conservative curation pass |
cognitive_status |
Graph and memory health metrics |
learning_run |
Detect contradictions, weak atoms, merge candidates, gaps |
ask_pending / answer_human |
Human-in-the-loop clarification |
decay_run |
Run decay cycle |
cleanup_sessions |
Remove expired session atoms |
cleanup_duplicates |
Remove duplicate session atoms |
reindex_embeddings |
Rebuild embeddings |
Error memory and preferences
| Tool | Purpose |
|---|---|
error_check |
Check past failures before doing a task |
error_log |
Record a mistake and the correction |
error_list |
Browse unresolved/resolved errors |
preference_search |
Search structured preferences |
Import and introspection
| Tool | Purpose |
|---|---|
import_markdown |
Import markdown notes into atoms |
memory_summary |
3-level summary: global → domain → detail |
stats |
Database statistics |
version |
Server version |
recall_session |
Search one OpenClaw session |
session_summary |
Summarize one OpenClaw session |
memory_contradict |
Supersede an old atom with a newer contradictory one |
list_contradictions |
List explicit contradiction/supersession records |
classify_memory_tier |
Infer the 3-tier class (episodic/semantic/procedural) |
memory_impact |
Impact analysis: what depends on this atom |
Backup, restore & export
| Tool | Purpose |
|---|---|
backup_database |
Create, list, verify, or clean up SQLite snapshots |
restore_database |
Restore from a backup (with automatic safety backup) |
export_all |
Export all memory data as portable JSON |
import_data |
Import from JSON (merge or replace mode) |
Web UI (optional)
Memory Engine includes an optional web UI for graph exploration, atom inspection, contradiction browsing, and impact analysis.
# In docker-compose.yml, add:
# environment:
# - MEM_UI_PORT=6000
# expose:
# - "6000"
Or run standalone:
python3 web_ui.py
# Open http://localhost:6000
Quick start with Docker
Option A — Use the pre-built image (recommended)
# docker-compose.yml
services:
memory-engine:
image: ghcr.io/simoneb79/memory-engine-mcp:2.1.0
ports:
- "8085:8085"
volumes:
- memory-data:/data
restart: unless-stopped
volumes:
memory-data:
docker compose up -d
Pin the version. Use an explicit tag like
:1.7.0in production. Avoid:latest— it can change without notice.
Option B — Build from source
git clone https://github.com/SimoneB79/memory-engine-mcp.git
cd memory-engine-mcp
cp docker-compose.yml docker-compose.local.yml
# Edit volume paths in docker-compose.local.yml if needed
docker compose -f docker-compose.local.yml up -d --build
Default endpoint:
http://localhost:8085/sse
Example MCP client config:
{
"mcpServers": {
"memory-engine": {
"url": "http://localhost:8085/sse",
"transport": "sse"
}
}
}
See docs/INSTALL.md for Docker, local Python, Claude Desktop, Cursor, and OpenClaw examples.
Local Python
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python server.py
Configuration
Main configuration file: config.json
Important environment variables:
| Variable | Default | Purpose |
|---|---|---|
MEMORY_DB_PATH |
/data/memory.db |
SQLite database path |
MARKDOWN_SOURCE |
/workspace/memory |
Markdown directory for import |
MEMORY_HOST |
127.0.0.1 |
Server bind address (secure default) |
MEMORY_PORT |
8085 |
SSE port |
MEMORY_API_TOKEN |
(none) | Optional API token for auth (see Security) |
OPENCLAW_AGENT_DB |
(none) | Preferred per-agent OpenClaw SQLite DB (schema 17) |
OPENCLAW_SESSIONS_DIR |
/sessions |
Legacy JSONL fallback when no agent DB is configured |
SESSION_DIGEST_DIR |
/data/session_digests |
Optional session digest output |
For the SQLite mount, WAL/SHM handling, filtering, and security boundary, see OpenClaw transcript ingestion.
Semantic search requires Ollama reachable from the container or host. Default:
{
"ollama": {
"enabled": true,
"host": "http://ollama:11434",
"model": "nomic-embed-text"
}
}
If you do not use Ollama, set ollama.enabled to false; FTS recall still works.
Memory model
Atoms have:
titlebodytype:fact,decision,event,preference,log,procedure,note, etc.domain: project or topic namespaceconfidenceweighttags- optional TTL
Bonds connect atoms with relation types:
is_a · part_of · depends_on · contradicts · refines · derived_from · detail_of · related_to
Example usage
remember(
title="Use PostgreSQL for analytics",
body="SQLite is kept for local memory, PostgreSQL is used for multi-user analytics.",
type="decision",
domain="project:analytics",
confidence=0.9,
tags=["database", "architecture"]
)
recall(query="what database did we choose for analytics?", limit=5)
working_set(
query="continue the analytics backend work",
domain="project:analytics",
limit=8,
graph_depth=1
)
Security
By default, Memory Engine runs in open mode (no auth) — safe for stdio or trusted local environments.
To enable API token auth:
// config.json
{
"security": {
"api_token": "your-secret-token",
"allow_remote": false
}
}
Or via environment variable:
MEMORY_API_TOKEN=your-secret-token
When auth is enabled:
- MCP SSE requests must include
Authorization: Bearer <token> - Web UI API endpoints require
?token=<token>or Bearer header - Server binds to
127.0.0.1unlessallow_remote: true - Input validation (title/body size limits) and rate limiting are always active
See CHANGELOG.md for the full list of security features.
Publishing and registries
This repository is prepared for MCP discovery:
- MCP Registry name:
io.github.simoneb79/memory-engine-mcp - Registry metadata:
server.json - Docker/OCI verification label: included in
Dockerfile - Client config example:
mcp.json
See docs/PUBLISHING.md for the publication checklist.
Repository status
- Public GitHub repository: https://github.com/SimoneB79/memory-engine-mcp
- Existing listing: https://mcpmarket.com/server/memory-engine
- License: MIT
License
MIT — see LICENSE.
Memory Engine MCP 질문
Memory Engine MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add memory-engine-mcp -- docker run -i --rm ghcr.io/simoneb79/memory-engine-mcp:1.5.3를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
Memory Engine MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
Memory Engine MCP는 어떤 도구를 제공하나요?
36개 도구를 제공합니다. 예: remember, recall, working_set, semantic_search, get_atom.
Memory Engine은 클라우드 API가 필요한가요?
아니요, SQLite 데이터베이스와 Ollama를 통한 선택적 로컬 임베딩을 사용하는 로컬 우선 시스템이므로 클라우드 API가 필요하지 않습니다.
기존 Markdown 노트를 사용할 수 있나요?
네, 사람이 읽을 수 있는 기존 파일을 대체하지 않고 메모리 시스템으로 기존 노트를 단방향으로 가져올 수 있습니다.
메모리 그래프를 시각화할 수 있는 방법이 있나요?
네, 그래프 탐색, 원자(atom) 검사 및 영향 분석을 위한 선택적 웹 UI를 사용할 수 있습니다.