Skip to content

teddashh/mcp-memory-server

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

9 Commits
mcp_memory
mcp_memory
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 
pyproject.toml
pyproject.toml
 
 
setup_config.py
setup_config.py
 
 

Repository files navigation

MCP Memory Server

Every interaction leaves a trace. Every trace becomes knowledge.

凡走過必留下痕跡。每個痕跡都將成為知識。

License: MIT Python 3.11+ MCP Compatible Tools CJK Ready

A unified long-term memory, knowledge base, and audit trail for AI agents.

統一的 AI Agent 長期記憶、知識庫與稽核軌跡系統。

Quick Start | Tools | Architecture | Salience | 繁體中文

The Problem / 問題

AI agents are stateless. They forget everything between sessions. Your decisions, your solved problems, your hard-won knowledge — gone. Every new conversation starts from zero.

Existing memory solutions are either too simple (flat key-value stores) or too opinionated (locked to one vendor, one database, one language).

AI 代理是無狀態的。它們在對話之間會遺忘所有事情。現有的記憶方案不是太簡單（扁平的 key-value），就是太限制（綁定單一廠商、資料庫、語言）。

The Solution / 解決方案

MCP Memory Server gives every AI agent a persistent brain with:

Any AI Agent ──→ MCP Tool Call ──→ Memory Server ──→ Local DB + Cloud DB
                 (native)          (auto-detect       (structured +
                                    workspace)         vector search)
What makes it different 獨特之處
Not just memory — a knowledge base. Decisions, questions, and knowledge are fundamentally different things. We store them differently. 不只是記憶——是知識庫。 決策、問題、知識本質不同，分別儲存。
Not just storage — intelligent recall. Salience tracking, access reinforcement, and natural decay surface what matters. 不只是儲存——是智慧回想。 Salience 追蹤、存取強化、自然衰減，讓重要的浮上來。
Not just local — cross-workspace. 18-table cloud schema with vector search across all your projects. 不只是本地——跨專案。 18 張表的雲端 schema，跨所有專案的向量搜尋。
Not just English — CJK-native. Token estimation built for Chinese, Japanese, Korean from day one. 不只是英文——原生 CJK。 Token 估算從第一天就為中日韓文設計。

Quick Start / 快速開始

git clone https://github.com/teddashh/mcp-memory-server.git
cd mcp-memory-server
pip install -e .

# Interactive setup (optional — works with SQLite defaults)
python setup_config.py

Claude Code

Add to ~/.claude/.mcp.json:

{
  "mcpServers": {
    "memory": {
      "command": "python",
      "args": ["-X", "utf8", "-m", "mcp_memory"],
      "cwd": "/path/to/mcp-memory-server"
    }
  }
}

Gemini CLI / Codex CLI

python -m mcp_memory --http  # → http://127.0.0.1:8787/mcp

Architecture / 系統架構

┌─ Claude Code ────────────┐
├─ Gemini CLI ─────────────┤
├─ Codex CLI ──────────────┼──→  MCP Memory Server (19 tools)
├─ Custom MCP Client ──────┤          │
└─ Any Future AI Tool ─────┘          │
                                      ├── L2: SQLite (local, fast, per-workspace)
                                      │     └── Salience tracking + CJK token estimation
                                      │
                                      ├── L3: Markdown (git-synced, human-readable)
                                      │     └── Knowledge files, daily logs
                                      │
                                      └── L4: Cloud DB (cross-workspace, vector search)
                                            └── 18 tables + audit trail + daily reports

The 4-Layer Memory Model / 四層記憶模型

L1  session.md       ← 短暫：當前對話的脈絡（每次載入，compact 控制大小）
      ↓ compact (agent-driven, CJK-aware token estimation)
L2  SQLite memory.db ← 結構化：每個專案獨立，salience 追蹤，毫秒級查詢
      ↓ sync (scheduled, incremental, idempotent)
L3  Markdown files   ← 永久：Git 同步，人類可讀，Obsidian 知識庫
L4  Cloud DB         ← 統一：跨專案向量搜尋，18 張表，完整稽核軌跡
Layer Storage Speed Scope 說明
L1 session.md Instant Current conversation 當前對話脈絡
L2 SQLite ~1ms Current workspace 當前專案的結構化記憶
L3 Markdown ~10ms Shared via git Git 同步的知識庫
L4 Cloud DB ~100ms All workspaces 跨所有專案 + 向量搜尋

Key principle: each layer only talks to its neighbor. No skipping layers.

核心原則：每層只與相鄰層互動，不跳層。

L1 ──compact──→ L2 ──sync──→ L4
     ↑ agent        ↑ scheduler
     主動            自動 (30min)

Query: L2 (fast) → L4 (cross-workspace)

MCP Tools (19) / 工具一覽

Write — Capture knowledge as it happens / 寫入——即時捕捉知識

Tool Description 說明
memory_store Smart store — auto-classifies type (decision/resolved/question/knowledge) 智慧儲存——自動分類類型
memory_record_decision Record a decision (what, why, how) 記錄決策（做什麼、為什麼、怎麼做）
memory_record_resolved Record a resolved issue 記錄已解決的問題
memory_record_question Record an open question (priority 1-3) 記錄未解問題（優先級 1-3）
memory_record_knowledge Record a knowledge item 記錄知識項目

Read — Recall what matters / 讀取——回憶重要的事

Tool Description 說明
memory_list List recent memories, filter by type 列出最近記憶，可按類型篩選
memory_get Get a specific memory by ID (auto-tracks access) 依 ID 取得（自動追蹤存取）
memory_get_summary Quick counts per workspace 快速查看各表計數

Delete / 刪除

Tool Description 說明
memory_delete Delete a memory by ID 依 ID 刪除記憶

Search — Find by meaning, not keywords / 搜尋——依語意查找

Tool Description 說明
memory_search Salience-weighted semantic search across all workspaces Salience 加權的跨專案語意搜尋

Salience — Important memories surface naturally / 記憶重要性——重要的自然浮上來

Tool Description 說明
memory_reinforce Manually boost a memory's salience (+20%) 手動強化記憶重要性（+20%）

Trail — Full audit trail / 軌跡——完整稽核

Tool Description 說明
memory_audit_search Search audit trail (keyword, date, sender, importance) 搜尋稽核軌跡
memory_audit_stats Audit statistics (by importance, direction, category) 稽核統計
memory_daily_report Daily reports (email stats, calendar, narrative) 每日報告
memory_activity_log Agent activity log (scheduled tasks, dispatches) 代理活動日誌

Admin / 管理

Tool Description 說明
memory_status System overview (local + cloud + trail + embeddings) 系統總覽
memory_compact CJK-aware session health check + compaction trigger CJK 感知的 session 健康檢查
memory_oracle_summary Cross-workspace summary from cloud 雲端跨專案摘要

Salience Engine / 記憶 Salience 引擎

Not all memories are equal. Some are accessed daily, others are forgotten. The salience engine ensures important memories surface naturally while noise fades away.

不是所有記憶都一樣重要。有些每天被查詢，有些被遺忘。Salience 引擎確保重要的記憶自然浮上來，噪音自然沈下去。

Inspired by memory-lancedb-pro's Weibull decay model, adapted for our multi-layer architecture.

How It Works / 運作方式

Memory born → salience = 1.0
     │
     ├── Accessed (memory_get / memory_search) → salience *= 1.05  (+5% per access)
     ├── Reinforced (memory_reinforce)          → salience *= 1.20  (+20% manual boost)
     │                                            cap at 2.0
     │
     └── Not accessed for 30+ days              → salience *= 0.95  (-5% daily decay)
                                                   floor at 0.01

Search results sorted by: salience DESC, then recency

Every memory_get and memory_search automatically tracks access. No manual intervention needed. Frequently used memories stay relevant. Stale memories gradually fade — but they're never deleted. They just sink lower in search results.

每次 memory_get 和 memory_search 自動追蹤存取。 不需手動操作。常用的記憶保持相關性。陳舊的記憶逐漸淡出——但永不刪除，只是在搜尋結果中排序靠後。

Fields Added to Every Memory / 每筆記憶加入的欄位

Field Type Description 說明
access_count Integer Total times accessed 總存取次數
last_accessed Timestamp When last read or searched 最後存取時間
salience Float (0.01–2.0) Current importance score 當前重要性分數

CJK-Aware Context Management / CJK 感知的 Context 管理

Standard token estimation assumes ASCII (~0.25 tokens/char). This underestimates CJK content by 3-6x, causing context window overflow and premature compaction.

標準的 token 估算假設 ASCII（~0.25 tokens/字元）。這低估 CJK 內容 3-6 倍，導致 context window 溢出。

Inspired by lossless-claw-enhanced's character-class approach:

Character Class Tokens/Char Examples
ASCII 0.25 Hello world → 3 tokens
CJK 1.5 你好世界 → 6 tokens
Emoji 2.0 Emoji sequences
Hiragana/Katakana 1.5 Japanese text
Korean Hangul 1.5 Korean text

Impact / 影響

Text: "資料庫 schema 部署完成，所有表都已經建好了。"

Standard estimate:  22 chars × 0.25 = 6 tokens   ← WRONG
CJK-aware estimate: 22 chars → 28 tokens          ← CORRECT (4.7x difference)

memory_compact uses CJK-aware estimation to accurately determine when session.md needs compaction:

[workspace] session.md status: COMPACT RECOMMENDED
  Lines: 142 | Chars: 5830 | Estimated tokens: 4102
  (CJK-aware: CJK=1.5tok, ASCII=0.25tok, Emoji=2.0tok)
  Threshold: 100 lines or 3000 tokens
  → Agent should: read session.md, extract items via memory_record_*, trim session.md

Memory Types / 記憶類型

Type When to Use Example
Decision You chose a path "Use Clerk for auth — lower maintenance"
決策 做出選擇時 「選用 Clerk 做認證——維護成本較低」
Resolved You fixed something "JWT race condition — fixed with mutex"
已解決 修好問題時 「JWT race condition——用 mutex 修復」
Question You need an answer "Should we add Redis?"
問題 需要答案時 「要不要加 Redis？」
Knowledge You learned something "VECTOR columns support cosine similarity"
知識 學到東西時 「VECTOR 欄位支援 cosine similarity」

memory_store auto-classifies: if it contains "decided/chose" → decision, "fixed/solved" → resolved, "?" → question, else → knowledge.

memory_store 自動分類：包含「決定/選擇」→ 決策，「修好/解決」→ 已解決，「？」→ 問題，其他 → 知識。

Audit Trail / 稽核軌跡

"Every interaction leaves a trace." — This is not just a tagline. It's the architecture.

「凡走過必留下痕跡。」 —— 這不只是標語，這是架構。

Table Scale Purpose 用途
AUDIT_LOG Scales to 100K+ Every email, message, and action — timestamped, categorized, suspicious-flagged 每封郵件和動作的完整紀錄
ACTIVITY_LOG Grows daily Agent scheduled task logs, dispatches, health checks 代理排程任務、派送、健康檢查
DAILY_REPORTS 1 per day Auto-generated daily summaries with email stats, calendar, narrative 自動產生的每日摘要
AUDIT_PROGRESS Per source Data source processing tracker 資料來源處理進度

Search by date, sender, keyword, importance (H/M/L), suspicious flag. Get aggregate stats by period.

Domain Isolation / 領域隔離

Every workspace belongs to a domain: work, personal, or system.

                    ┌─────── work ───────┐
                    │ project-a          │
                    │ project-b          │  ← Write isolated
                    │ report-automation  │  ← Read: current workspace default
                    └────────────────────┘
                              ↕ cross-domain search (opt-in)
                    ┌────── personal ─────┐
                    │ my-app              │  ← Separate domain
                    │ side-projects       │
                    └─────────────────────┘
  • Write always goes to the current workspace / 寫入永遠寫到當前專案
  • Read defaults to current workspace / 讀取預設只看當前專案
  • Search can span all domains (opt-in) / 搜尋可跨領域（需明確指定）

Database Schema (18 Tables) / 資料庫結構（18 張表）

Click to expand full schema / 點擊展開完整 schema
Table Purpose 用途
WORKSPACES Project registry with domain tags 專案註冊表
DECISIONS Decisions (what/why/how) + salience 決策記錄 + salience
RESOLVED Resolved issues + salience 已解決問題 + salience
OPEN_QUESTIONS Prioritized questions + salience 未解問題 + salience
KNOWLEDGE_ITEMS Knowledge + vector embeddings + salience 知識 + 向量嵌入 + salience
DAILY_LOGS Daily log metadata 每日日誌
PERSONALITY_TRAITS Structured user understanding 用戶特質
CROSS_REFERENCES Links between any records 記錄間關聯
TAXONOMY Hierarchical categories 階層分類
CONTACTS People and relationships 聯絡人
SOP Standard operating procedures 標準作業流程
CHANNELS Communication channels 通訊管道
ACTIVITY_LOG Agent action trail 代理動作軌跡
AUDIT_LOG Full audit trail 完整稽核軌跡
AUDIT_PROGRESS Processing tracker 處理進度
DAILY_REPORTS Auto-generated summaries 每日摘要
SYNC_WATERMARK Incremental sync tracking 增量同步追蹤
SYNC_LOG Sync history 同步歷史

Supported Cloud Backends / 支援的雲端後端

Backend Status Vector Search
SQLite Built-in (default) Text search
Oracle AI Database Supported Native VECTOR + cosine
PostgreSQL + pgvector Planned vector extension
Supabase Planned pgvector + REST API
MySQL / HeatWave Planned ML integration

How It Compares / 與其他方案的比較

Feature MCP Memory Server OpenMemory memory-lancedb-pro
Structured memory types 4 types key-value 6 categories
Cross-workspace search cloud DB local only local only
Vector search Oracle / pgvector synthetic embeddings LanceDB
Salience / decay access tracking + daily decay no Weibull model
CJK token awareness built-in no no
Audit trail 86K+ entries no no
Multi-agent support Claude + Gemini + Codex Claude + Gemini + Codex OpenClaw only
Domain isolation work / personal / system user ID scope-based
Cloud sync scheduled incremental no no
Database choice SQLite + any cloud DB SQLite LanceDB
18-table schema yes no no

Configuration / 設定

~/.mcp-memory/config.json:

{
  "workspace_root": "~/Documents/Workspace",
  "workspace_map": "~/path/to/workspace-map.json",
  "cloud_db": {
    "enabled": false,
    "type": "oracle | postgresql | supabase",
    "connection": "..."
  },
  "embedding": {
    "provider": "none | openai | local",
    "model": "text-embedding-3-small"
  }
}

Interactive setup: python setup_config.py

Transport modes:

python -m mcp_memory            # STDIO (Claude Code)
python -m mcp_memory --http     # HTTP (Gemini, Codex, web)
python -m mcp_memory --decay    # Run daily salience decay job

Philosophy / 設計哲學

"The best knowledge system captures everything and surfaces only what's relevant."

「最好的知識系統是捕捉一切，只呈現相關的。」

  1. Structured by default — Decisions and knowledge are different. Treat them differently.
  2. Salience, not deletion — Old memories fade, but never disappear. They can always be found.
  3. Layers, not monoliths — Each layer has a job. Fast local → permanent cloud. No skipping.
  4. CJK-native — Not an afterthought. Built for multilingual from the start.
  5. Agent-agnostic — Your memory belongs to you, not your AI vendor.
  6. Audit everything — Every trace, every action, every day. Full accountability.
  1. 結構化為本 —— 決策和知識本質不同，分別儲存。
  2. Salience 而非刪除 —— 舊記憶淡出，但永不消失。隨時可找回。
  3. 分層而非單體 —— 每層各司其職。快速本地 → 永久雲端。不跳層。
  4. 原生 CJK —— 不是事後補丁。從第一天就為多語言設計。
  5. 不綁定 AI —— 你的記憶屬於你，不屬於 AI 廠商。
  6. 稽核一切 —— 每個軌跡、每個動作、每一天。完整的可追溯性。

繁體中文版

完整繁體中文說明

MCP Memory Server 是什麼？

一個統一的 AI 代理長期記憶系統。安裝後，你的 Claude Code、Gemini CLI、Codex CLI 都能使用 19 個 native MCP tools 來記錄和查詢記憶。

核心功能

  • 19 個 MCP 工具：寫入（5）、讀取（3）、刪除（1）、搜尋（1）、Salience（1）、稽核軌跡（4）、管理（3）
  • 四層記憶架構：session.md → SQLite → Markdown → Cloud DB
  • Salience 引擎：存取追蹤 + 強化 + 自然衰減，重要的記憶自動浮上來
  • CJK 感知：繁中/日文/韓文的 token 估算準確度提高 3-6 倍
  • 領域隔離：工作、個人、系統三個領域，寫入隔離，搜尋可跨域
  • 稽核軌跡：AUDIT_LOG + ACTIVITY_LOG + DAILY_REPORTS，完整可追溯
  • 18 張表的雲端 Schema：涵蓋記憶、知識、聯絡人、SOP、分類樹、稽核
  • 離線優先：SQLite 零配置即可運作，雲端資料庫是可選的進階功能

安裝

git clone https://github.com/teddashh/mcp-memory-server.git
cd mcp-memory-server && pip install -e .
python setup_config.py

在 ~/.claude/.mcp.json 加入 server 設定後，重啟 Claude Code 即可使用所有 tools。

Contributing / 貢獻

Issues and PRs welcome.

歡迎提交 Issue 和 Pull Request。

License

MIT

About

MCP Memory Server — unified long-term memory for AI agents (SQLite + Oracle + Vector Search)

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages