Memmy：VPS 上供 AI agent 共用的本機記憶中樞

Memmy 的用途與儲存內容

Memmy 是在自有 VPS（虛擬私有伺服器）上執行的 AI 代理程式本機記憶體中樞。它會將代理程式學到的內容儲存在單一 SQLite 資料庫中，該主機上的每個代理程式都會讀取及寫入相同的資料存放區。此專案由 MemTensor memmy-agent，採用 MIT 授權；截至 1 November 2026，版本為 1.2.401；Memory 則獨立採用 2.1.7 版本。

在伺服器上，只有其中一部分功能重要。Memmy 提供在 http://127.0.0.1:18960 上監聽的記憶體服務、會與該服務通訊的 memmy-memory 命令列介面（CLI），以及桌面工作台。工作台僅提供 macOS 和 Windows 套件，因此在 Linux VPS 上只需執行服務和 CLI。這已足以讓 Claude Code、Codex 和 Cursor 共用記憶體。

Memmy 將儲存內容分成 4 個層級。Capture 會先個別儲存 Raw Turn，接著針對每個擷取步驟寫入 1 個 L1 Trace 項目，其中包括請求、回應、工具呼叫及結果。L2 Policy 是從證明實用的 trace 中歸納出的程序。L3 World Model 是關於專案或環境的穩定知識。Skill 則是從 policy 凝鍊出的可呼叫程序。Capture 會建立 L1 trace，背景工作會逐步發展較高層級，而明確寫入時可以選取層級。如果這些區分仍然抽象，記憶體是學習建置代理程式的分階段路徑中較後面的階段；當你自行寫過簡單的代理程式迴圈，並觀察它在每次執行之間忘記所有內容後，這些層級會更容易理解。

共享記憶體中樞與各工具個別記憶體的差異

目前每個代理程式都有自己的記憶體。Claude Code 將指示檔案存放在 repository 中。Cursor 將規則存放在 workspace database 中。Codex 將工作階段日誌存放在 ~/.codex。每個儲存區都隸屬於單一工具，因此您在某個工具中於星期一教過的資訊，到了星期二在另一個工具中仍然不存在。這會產生兩種成本：一是重複說明同一個專案所消耗的 token，二是代理程式根據您已在其他地方修正過的假設執行錯誤工作。

中樞會將儲存區移出工具之外。Memmy 也會讀取現有的儲存區，因此您不必從空白資料庫開始。其掃描器內建十種來源：位於 ~/.claude/projects/**/*.jsonl 的 Claude Code、位於 ~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-*.jsonl 的 Codex、位於 ~/.local/share/opencode/opencode.db 的 OpenCode、Cursor 的 state.vscdb 檔案、位於 ~/.openclaw 的 OpenClaw SQLite databases、位於 ~/.hermes 的 Hermes、位於 ~/.dsh/sessions 的 DeepSeek Harness、位於 ~/.workbuddy/projects 的 WorkBuddy、位於 ~/.pi/agent/sessions 的 Pi，以及位於 ~/.qwenworkcn/projects 的 QwenWork。桌面工作台可以依名稱新增其他代理程式；只有在找不到該代理程式時，才會要求提供其歷史紀錄路徑。伺服器端掃描器不支援自訂來源，因此在 headless VPS 上只能使用內建來源。

匯入計數不一致是正常的。掃描器會依來源和對話分組訊息，然後為每個完整回合寫入一筆 L1 記憶。回合必須包含非空白的使用者內容，且以非空白的代理程式訊息結束，才算完整。因此，不完整的回合必須等到後續同步完成後才會產生資料。訊息會透過對話檢查點和穩定的回合 ID 去除重複。同一次執行中的掃描數、匯入訊息數與新增記憶數可能都不同。

這一節與Claude Code 如何在單一工作階段中管理內容相互搭配。內容管理決定單一視窗能容納哪些內容。記憶體中樞則決定視窗關閉後哪些內容仍會保留。

VPS 需要的項目

• Node.js 22 或更新版本。Memmy 文件要求此版本，而 Ubuntu 24.04 隨附 Node 18。
• git 與建置工具鏈，因為 better-sqlite3 是原生模組，安裝期間可能需要編譯。
• 足以執行 root 工作區安裝及其前端建置工具鏈的 RAM。
• 足以存放 node_modules 與資料庫的可用磁碟空間。

sudo apt update
sudo apt install -y git build-essential python3 curl ca-certificates sqlite3
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version

node --version 應針對文件所述的原始碼建置輸出 v22 或更高版本。若此處顯示 v18，表示 NodeSource 步驟未生效。npm 的 engine-strict 預設為 false，因此不相容的引擎宣告通常只會產生警告，不會自動使安裝失敗。

從原始碼在 Ubuntu 24.04 安裝 Memmy

git clone https://github.com/MemTensor/memmy-agent.git
cd memmy-agent
cp .env.example .env
npm install
npm run memory:build

npm run memory:build 會將 @memmy/memory workspace 編譯為 Memory/dist。它也會建置 AgentSourceCore、記憶體檢視器，以及該 workspace 所需的整合資產。確認原生模組已載入：

node -e "const Database = require('better-sqlite3'); const db = new Database(':memory:'); db.close(); console.log('better-sqlite3 loads')"

如果該行不是輸出結果而是拋出錯誤，請讀取錯誤訊息，以判斷是載入失敗還是資料庫初始化失敗。若是原生模組不相容，請執行 npm rebuild better-sqlite3。這正是專案自己的啟動指令碼在啟動任何元件前執行的命令。

README 將 bash scripts/dev-start.sh 說明為單一命令啟動方式。請勿在無頭 VPS 上執行。它會啟動 Electron 桌面 shell，以及在 19000 埠上執行的 Vite 開發伺服器，並與記憶體服務並行啟動。Electron 需要顯示器，因此在沒有圖形工作階段的伺服器上，該指令碼會停滯或結束。

近期版本也提供適用於 Linux x64 和 arm64 的 memmy-agent-linux-cli.tar.gz 與 install.sh。安裝程式需要 22.x 中的 Node.js 22.23.4+、24.x 中的 24.22.1+，或 26.x 中的 26.12.1+，以及 systemd 使用者工作階段；其他 major version 會被拒絕。它會將 memmy 和 memmy-memory 啟動器放入 ~/.local/bin，並以使用者 unit 的形式在 127.0.0.1:18960 上啟動記憶體服務。本指南仍採用從原始碼建置，因為這種方式可以在每個指令碼執行前先讀取其內容。

啟動 memory service 並確認它能回應

npm run memory:serve:dev

這是從原始碼執行 memory service 的文件指定方式。它會繫結至 127.0.0.1:18960，將資料庫保存在 ~/.memmy/memory-service/memory.sqlite，並從 ~/.memmy/config.yaml 讀取設定。若需要明確指定，也可以將相同值作為 flags 傳入 server：

npm run memory:serve:dev -- \
  --host 127.0.0.1 --port 18960 \
  --db ~/.memmy/memory-service/memory.sqlite \
  --config ~/.memmy/config.yaml

在第二個 shell 中，詢問 service 是否正在執行：

curl -sS http://127.0.0.1:18960/api/v1/health

Health check 不需要 token，因此適合作為探測方式。如果 curl 以 code 7 結束並顯示 Failed to connect to 127.0.0.1 port 18960 訊息，表示連線失敗；但這本身無法確認是否存在 listener。請檢查 address、port 與本機 firewall，並查看執行 service 的 terminal 是否有啟動錯誤。service 啟動後，ss -lntp | grep 18960 可確認 socket 已建立。

其餘 HTTP API（application programming interface）位於 /api/v1 底下。

• POST /api/v1/memory/add 寫入 memory，POST /api/v1/memory/search 執行查詢。
• GET /api/v1/memory/:id 與 DELETE /api/v1/memory/:id 讀取並移除單一項目。
• POST /api/v1/sessions/open 與 POST /api/v1/sessions/:sessionId/close 包住一個 agent session。
• POST /api/v1/turns/start 與 POST /api/v1/turns/:turnId/complete 記錄一個回合。
• GET /api/v1/panel/overview、/api/v1/panel/analysis 與 /api/v1/panel/items 將資料提供給 dashboard。

Memmy 保留一組連接埠；在 headless 模式下只會使用其中前幾個：18960 用於 memory、18970 用於 gateway health、18980 用於 web UI 與 admin HTTP、18990 用於由 memmy serve 啟動的 OpenAI-compatible API，接著是 19000，供 desktop frontend 的 Vite dev server 使用，以及 19001，供其 hot reload socket 使用。專案的 ports 頁面仍列出 19010 作為 hot reload 連接埠，但 Vite config 設定的是 19001。如果你的主機上已有其他程式占用其中一個連接埠，請從該頁面開始查找。

memmy-memory 指令的實際來源

這是首次安裝最容易出錯的地方，因此請直接從套件讀取資訊，不要自行猜測。指令名稱與 repository 名稱無關。它來自定義該指令之 workspace 的 bin 欄位：

node -p "JSON.stringify(require('./Memory/package.json').bin)"

此指令會輸出 {"memmy-memory":"./dist/src/cli/index.js"}。因此，建置後的 entry point 是 Memory/dist/src/cli/index.js，而且只有在 npm run memory:build 之後才會存在，因為建置程序會建立 dist 並將檔案標記為可執行。請直接執行：

node Memory/dist/src/cli/index.js health

如果希望在 PATH 中使用簡短名稱，請將同一個檔案建立連結：

sudo ln -s "$PWD/Memory/dist/src/cli/index.js" /usr/local/bin/memmy-memory
memmy-memory health

CLI 預設使用 http://127.0.0.1:18960，並接受 --url、--token、--config、--source 與 --user-id。其子命令包括 init、health、search、add、get 與 delete，另有供 agent 使用、而非供人員使用的 session 與 turn 呼叫，以及用於管理服務本身的 install、upgrade、service 與 stop。memmy-memory search "deploy steps" 與 memmy-memory add "staging migrates on deploy" 是 agent 最常執行的兩個指令。

如何將 Claude Code 連接至 Memmy？

Memmy 不會在 Claude Code 中將自己註冊為伺服器。它會透過 Claude Code 已經會讀取的檔案進行連接，而實際功能取決於你執行的 memmy-memory。如果使用原始碼 checkout，memmy-memory init --agent claude 會將 memmy-memory Skill 寫入 ~/.claude/skills/，並將帶有標記的記憶區塊寫入 ~/.claude/CLAUDE.md；之後，當這些指示要求 Claude Code 執行時，Claude Code 會將 memmy-memory 當作一般 shell 命令執行。Linux 安裝程式放入 ~/.local/bin 的 launcher 會進一步處理：同一個命令也會在 ~/.claude/settings.json 中，針對 SessionStart、UserPromptSubmit、Stop、PostCompact 和 SessionEnd 註冊 hooks。這些 hooks 會注入相關記憶，並儲存每次完成的回合，不必由模型自行決定是否執行。

請手動撰寫一次這項指示，這樣才能確切知道代理程式收到的內容。Claude Code 會在每次工作階段開始時，從專案根目錄讀取 CLAUDE.md。因此，在原始碼路徑上，以下這類區段就是完整的整合設定：

## Memory

Before starting a task, run `memmy-memory search "<topic>"` and read what comes back.
When a task is done, run `memmy-memory add "<what you learned>"` for anything that will matter next session.

請明確了解這項設定能提供什麼功能。沒有 hooks 時，這只是指示層級的整合，因此只有在模型決定執行命令時才會運作。沒有任何機制會強制執行該呼叫。如果工作階段結束時沒有執行 add，這項指示本身不會儲存任何內容；之後仍可透過掃描歷史記錄，匯入已完成的回合。這與Claude Code 自己的記憶檔案有相同的取捨，但有一項差異：儲存區是共用的，因此同一台機器上的 Codex 和 Cursor 也能取得這則記錄。Hooks 會主動補足這項缺口，而不是僅依賴模型執行；這也是為什麼持久記憶會與預算上限及權限規則一樣，列在值得安裝的 DeepSeek Harness 外掛中。

反向整合完全不需要設定。Memmy 的 scanner 已經會讀取 ~/.claude/projects/**/*.jsonl，Claude Code 會將工作階段逐字記錄寫入該位置。只要在執行於 tmux 工作階段中的 Claude Code的同一台伺服器上執行 Memmy，昨天的工作就會在不需額外設定的情況下成為記憶。

Memmy 能作為 Claude Code 的 MCP 伺服器嗎？

不能。先了解這個方向，可以省下大量時間。MCP（model context protocol）包含用戶端與伺服器。Memmy 是用戶端，會向外連線至 MCP 伺服器，並將其工具提供給自身的 agent runtime。它不會發布可供 claude mcp add 指向的 MCP endpoint。儲存庫中唯一的 MCP bridge 屬於桌面本機 API 內的 Composio integration，而該 API 會在 127.0.0.1 上繫結隨機埠，並使用自身的 x-memmy-mcp-token header。

用戶端設定位於 ~/.memmy/config.yaml 所指向的 MEMMY_CONFIG 檔案中，路徑為 tools.mcpServers：

tools:
  mcpServers:
    example:
      type: stdio
      command: npx
      args:
        - "-y"
        - "your-mcp-server"
      toolTimeout: 30
      enabledTools:
        - "*"

type 接受 stdio、sse 與 streamableHttp。stdio 伺服器會作為 Memmy 的子程序執行，因此其 command 必須存在於同一台主機上，並以相同使用者身分執行。如果你已在 VPS 上執行 MCP 伺服器，請將這些伺服器列在此處。

維持記憶儲存區的私有性

Memmy 使用的所有內容都位於 ~/.memmy 下，包括 config.yaml、工作區、memory-service/memory.sqlite 與執行階段檔案。掃描與擷取程序都在本機執行，記憶也會寫入本機的 SQLite 檔案，因此預設設定確實是完全本機化。

雲端連線是需要留意的一條路徑。MEMMY_CLOUD_SERVICE 指定雲端來源。程式碼未設定預設值，但 .env.example 會將其設為 https://api.memmy.cn，安裝步驟則會把該檔案複製到 .env。這會讓帳號模式使用試用權杖；只要設定了此值，Memmy 的分析程式也會將使用事件傳送到該處，即使使用 API key 模式也是如此。傳送內容包括事件名稱與命令名稱、版本及安裝 ID。CLI 只會回報固定的命令文字，不會傳送搜尋查詢或記憶文字。當此值未設定時，分析程式不會傳送任何資料。因此，在只使用 API key 的伺服器上，啟動任何服務前，請先清空 .env 中的該行。記憶改善計畫則是隱私設定中的獨立切換項目。

模型呼叫是另一條資料傳輸路徑。如果設定代管的 embedding provider，待嵌入的記憶文字會傳送給該 provider，以轉換成向量。本機儲存無法阻止這項傳輸。請使用內建的本機 embedding provider，或自行代管的 embedding endpoint，以關閉這條路徑。代管的摘要、演進與相關性篩選模型，在執行這些工作時也會接收記憶內容，因此也請檢查這些模型的設定。

請讓 port 18960 綁定在 loopback 位址。這不需要防火牆規則，因為綁定至 127.0.0.1 的服務完全無法從本機以外連線。請改用 SSH 從筆記型電腦連入：

ssh -N -L 18960:127.0.0.1:18960 you@your-vps

目前的記憶服務會拒絕非 loopback 的綁定位址。在設定檔中設定 storage.token，或設定 MEMMY_MEMORY_TOKEN、MEMORY_SERVICE_TOKEN 環境變數，即可使用 bearer token 保護一般的記憶 API 呼叫；health endpoint 維持未驗證狀態，而瀏覽器檢視器會對本機請求使用獨立的檢查機制。設定值支援 ${ENV_NAME} 參照，因此 token 與模型 API keys 不必直接寫入檔案。這與在其他地方 避免將機密交給 AI agents 的做法相同；如果未來版本變更預設綁定位址，預設拒絕的 ufw 政策 就是最後一道防線。

信任 ~/.memmy 前先備份

memory.sqlite 是完整的資料儲存檔。向量透過 sqlite-vec 擴充功能儲存在同一個檔案中，因此備份一個檔案即可。服務寫入資料時使用 cp 複製檔案，可能會取得損毀的資料庫。請使用 SQLite 內建的備份指令：

mkdir -p ~/memmy-backup
sqlite3 ~/.memmy/memory-service/memory.sqlite ".backup '$HOME/memmy-backup/memory.sqlite'"

這會在服務持續執行時建立一致的複本。請依排程將複本傳送到該主機之外的儲存位置；restic 傳送至異地儲存就是用於此目的。遺失 config.yaml 時，您只需重新輸入提供者設定。遺失 memory.sqlite 時，則會遺失上次可用備份之後記錄的記憶；服務也會在 schema migration 前建立本機備份，但那不是目前的異地複本。

在 systemd 下執行記憶體服務

npm run memory:serve:dev 在 shell 中執行時，shell 結束後程序也會結束。unit 檔案可讓服務在重新開機後持續執行。服務會以 memmy 使用者身分執行，使用 /opt/memmy 中的 checkout，並將設定檔放在該使用者的家目錄。先停止 shell 中執行的副本，再搬移 checkout 與設定檔，並重新指定 memmy-memory 連結：

sudo useradd -m -s /bin/bash memmy
sudo mkdir -p /opt/memmy
sudo mv ~/memmy-agent /opt/memmy/memmy-agent
sudo chown -R memmy:memmy /opt/memmy
sudo ln -sfn /opt/memmy/memmy-agent/Memory/dist/src/cli/index.js /usr/local/bin/memmy-memory
sudo install -d -o memmy -g memmy -m 700 /home/memmy/.memmy
sudo install -o memmy -g memmy -m 600 ~/.memmy/config.yaml /home/memmy/.memmy/config.yaml
sudo install -d -m 755 /etc/memmy

服務會將資料庫存放在 /home/memmy/.memmy，因此啟動時會使用空的資料庫。

[Unit]
Description=Memmy memory service
After=network-online.target

[Service]
Type=simple
User=memmy
WorkingDirectory=/opt/memmy/memmy-agent
EnvironmentFile=/etc/memmy/memory.env
ExecStart=/usr/bin/npm run memory:serve:dev
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

不要將 token 放在 unit 中。請將它放在 /etc/memmy/memory.env，擁有者設為 root，權限設為 600：

MEMMY_CONFIG=/home/memmy/.memmy/config.yaml
MEMMY_MEMORY_TOKEN=replace-this-with-a-long-random-string

sudo systemctl daemon-reload
sudo systemctl enable --now memmy-memory
systemctl status memmy-memory --no-pager
curl -sS http://127.0.0.1:18960/api/v1/health

狀態輸出中的 status=203/EXEC 表示 systemd 完全無法執行 ExecStart，因此請檢查 which npm：在 NodeSource 安裝中，它位於 /usr/bin/npm；在 nvm 中，則位於使用者家目錄下的某個路徑，而 systemd 找不到該路徑。服務若啟動後立即結束，請檢查其結束狀態與 journal：代碼 0 表示正常結束，其他結果則包括非零結束狀態、訊號及逾時。請執行 journalctl -u memmy-memory -n 50 查看服務輸出。其操作方式與VPS 上的其他 systemd 服務相同。

此專案現在提供兩種使用者層級的替代方案。README 中針對原始碼建置的方式是 memmy-memory install --service-only，會下載固定版本的 Memory runtime 並註冊使用者服務；Linux 安裝程式則會將 memmy-memory.service 設定為 systemd --user unit。兩者都不會啟用 linger，因此請執行 sudo loginctl enable-linger <user>，讓該使用者的服務管理器在登出後持續執行，並在開機時啟動。

Memmy 目前尚未提供的功能

• 目前沒有 Linux 桌面版。封裝指令碼涵蓋 macOS 和 Windows，因此 workbench 與 onboarding wizard 無法在伺服器本機使用。memory service 現在已在 http://127.0.0.1:18960/viewer/ 提供瀏覽器檢視器，可透過上述 SSH tunnel 存取。Linux 則提供 CLI tarball 和 install.sh。
• memory:serve:dev 會透過 tsx 執行 TypeScript 進入點，這是開發用途的路徑。此 repository 也提供編譯輸出的 memory:serve。不帶參數執行 npm run，即可查看目前 checkout 實際提供哪些 scripts。
• Retrieval 會從最新的 2,000 筆 vector rows 建立搜尋範圍，再在該範圍內套用 Top-K 選取。在非常大的 store 中，較早的 memory 可能位於搜尋範圍之外。
• Embedding 會在 capture 之後執行，失敗時會進入 retry queue，不會阻塞 agent 的回合。剛加入的 memory 可能尚未能透過 vector search 找到。
• 另一台使用自己本機 SQLite database 的伺服器，具有獨立的 memory。

截至 1 November 2026 的 Version 1.2.401 仍顯示這是一個快速發展中的早期專案。Flags、paths 和 script names 會在不同 releases 之間變更。請查看自己 checkout 中的 bin 欄位及 npm run 的輸出，不要直接信任從任何地方複製的 command，包括此處的內容。

FAQ

為什麼 health check 會回傳 connection refused？

curl 的結束碼 7 搭配 Failed to connect to 127.0.0.1 port 18960 表示連線失敗，但無法判斷 Memmy 是已停止、已當機、正在其他位置監聽，或無法存取。請檢查位址與連接埠，執行 ss -lntp | grep 18960，並查看服務啟動所在的終端機或 journal。若日誌回報原生 SQLite 模組不相符，請執行 npm rebuild better-sqlite3。也請檢查 Node 版本：來源文件要求 Node 22 或更新版本；Linux installer 僅接受 22.x 中的 Node.js 22.23.4+、24.x 中的 24.22.1+，或 26.x 中的 26.12.1+。

從原始碼建置後，memmy-memory 命令從何而來？

它來自 @memmy/memory workspace package 的 bin 欄位，而不是 repository 名稱。請在 checkout 目錄內執行 node -p "JSON.stringify(require('./Memory/package.json').bin)"，該命令會輸出 {"memmy-memory":"./dist/src/cli/index.js"}。該檔案只有在執行 npm run memory:build 後才會存在，因為建置流程會建立 dist 並將檔案標記為可執行。請以 node Memory/dist/src/cli/index.js health 執行，或將它建立 symbolic link 到 /usr/local/bin，以使用簡短名稱。

可以使用 claude mcp add 將 Memmy 加入 Claude Code 嗎？

不行。Memmy 是 MCP client，不是 MCP server。它會連出至 ~/.memmy/config.yaml 中 tools.mcpServers 所列的 server，並將這些 server 的工具提供給自己的 runtime。Claude Code 則透過以 shell command 執行 memmy-memory CLI 的方式連接 Memmy。memmy-memory init --agent claude 會寫入一個 Skill 與 CLAUDE.md 區塊，告知 Claude Code 何時使用 Memmy；Linux installer 的 launcher 也會加入 Claude Code hooks，自動儲存每次對話。

執行 Memmy 會將我的記憶傳送到 cloud service 嗎？

掃描與擷取程序都在本機執行，記憶會寫入您自己磁碟上的 ~/.memmy/memory-service/memory.sqlite。MEMMY_CLOUD_SERVICE 在 .env.example 中設為 https://api.memmy.cn 時，會處理 account mode 與 trial token，並接收不含記憶文字的使用分析資料。若您只使用 API key，請將其清空。記憶改善計畫另有獨立的隱私切換選項。Hosted embedding model 會接收要轉換為向量的記憶文字；若要讓這項處理留在本機，請使用內建的 local provider，或使用您自行執行的 endpoint。Hosted summary、evolution 與 relevance-filter model 在執行這些工作時，也會接收記憶內容。