Panduan

Oleh Matt Connor 2026-07-31 · Dikemas kini 2026-08-01

Memmy: Hab Memori Setempat untuk Ejen AI di VPS

Q: Dari manakah datangnya perintah memmy-memory selepas binaan daripada kod sumber?

Perintah itu datang daripada medan bin dalam pakej ruang kerja @memmy/memory, bukan daripada nama repositori. Jalankan node -p "JSON.stringify(require('./Memory/package.json').bin)" dalam checkout dan perintah itu akan mencetak {"memmy-memory":"./dist/src/cli/index.js"}. Fail tersebut hanya wujud selepas npm run memory:build kerana binaan mencipta dist dan menandakan fail itu sebagai boleh laksana. Jalankannya sebagai node Memory/dist/src/cli/index.js health, atau buat symlink kepadanya dalam /usr/local/bin untuk nama ringkas.

Ketahui cara membina Memmy 1.0.4 daripada sumber di Ubuntu, menjalankan perkhidmatan pada port 18960 dan menyimpan semua nota secara setempat.

Memmy dan perkara yang disimpannya

Memmy ialah hab memori setempat untuk ejen AI yang berjalan pada VPS (pelayan peribadi maya) anda sendiri. Memmy menyimpan satu pangkalan data SQLite yang mengandungi perkara yang telah dipelajari oleh ejen anda. Setiap ejen pada pelayan tersebut membaca dan menulis stor yang sama. Projek ini ialah memmy-agent daripada MemTensor, dilesenkan di bawah MIT, dan berada pada versi 1.0.4 pada Julai 2026.

Hanya sebahagian daripadanya diperlukan pada pelayan. Memmy menyediakan perkhidmatan memori yang mendengar pada http://127.0.0.1:18960, antara muka baris perintah (CLI) memmy-memory yang berkomunikasi dengan perkhidmatan tersebut, dan meja kerja desktop. Meja kerja itu hanya dipakejkan untuk macOS dan Windows. Oleh itu, pada VPS Linux, anda menjalankan perkhidmatan dan CLI. Ini mencukupi untuk memberikan Claude Code, Codex dan Cursor memori yang dikongsi.

Memmy menyusun perkara yang disimpannya kepada empat lapisan. L1 Trace ialah giliran mentah: permintaan, respons dan panggilan alat. L2 Policy ialah prosedur yang diperoleh daripada jejak yang terbukti berguna. L3 World Model ialah pengetahuan stabil tentang projek atau persekitaran. Skill ialah prosedur yang boleh dipanggil dan dibentuk daripada dasar. Perkhidmatan menetapkan lapisan apabila ia menerima giliran. Oleh itu, anda tidak perlu menciptanya secara manual.

Perubahan hab memori dikongsi berbanding memori mengikut alat

Setiap ejen kini disertakan dengan memori sendiri. Claude Code menyimpan fail arahan dalam repositori. Cursor menyimpan peraturan dalam pangkalan data ruang kerjanya. Codex menyimpan log sesi di bawah ~/.codex. Setiap stor hanya dimiliki oleh satu alat. Oleh itu, fakta yang anda ajarkan pada hari Isnin dalam satu alat tidak diketahui oleh alat lain pada hari Selasa. Anda menanggung kos itu dua kali: pertama, dalam token yang digunakan untuk menerangkan semula projek yang sama; kedua, dalam kerja yang salah apabila ejen bertindak berdasarkan andaian yang telah anda betulkan di tempat lain.

Hab memindahkan stor itu keluar daripada alat. Memmy juga membaca stor sedia ada, jadi anda tidak bermula dengan pangkalan data kosong. Pengimbasnya mengenali enam sumber: Claude Code di ~/.claude/projects/**/*.jsonl, Codex di ~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-*.jsonl, OpenCode di ~/.local/share/opencode/opencode.db, fail state.vscdb milik Cursor, pangkalan data SQLite OpenClaw di bawah ~/.openclaw, dan Hermes di bawah ~/.hermes. Anda boleh menambah sumber secara manual dengan memberikan nama dan laluan setempat.

Kiraan import tidak akan sepadan, dan itu memang dijangka. Pengimbas mengumpulkan mesej mengikut sumber dan perbualan, kemudian menulis satu memori L1 bagi setiap giliran lengkap. Sesuatu giliran dikira lengkap apabila kandungan pengguna tidak kosong dan giliran itu berakhir dengan mesej pembantu yang tidak kosong. Oleh itu, sesi yang terhenti tidak menyumbang apa-apa. Mesej dinyahduplikasi menggunakan titik semak perbualan dan ID giliran yang stabil. Bilangan yang diimbas, bilangan mesej yang diimport dan bilangan memori baharu semuanya berbeza dalam pelaksanaan yang sama.

Ini ialah komponen yang melengkapi cara Claude Code mengurus konteks dalam satu sesi. Pengurusan konteks menentukan perkara yang boleh dimuatkan dalam satu tetingkap. Hab memori menentukan perkara yang kekal selepas tetingkap itu ditutup.

Keperluan pada VPS

Node.js 22 atau lebih baharu. Dokumentasi Memmy memerlukannya, manakala Ubuntu 24.04 menyediakan Node 18.
git dan rantaian alat binaan, kerana better-sqlite3 ialah modul natif yang mungkin dikompil semasa pemasangan.
Kira-kira 2 GB RAM. Pemasangan root memuat turun ruang kerja yang besar dan rantaian binaan frontend.
Beberapa GB ruang cakera kosong untuk node_modules dan pangkalan data.

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 sepatutnya memaparkan v22 atau lebih tinggi. v18 di sini bermakna langkah NodeSource tidak berjaya, dan pemasangan kemudiannya akan gagal semasa pemeriksaan enjin projek.

Pasang Memmy daripada sumber pada Ubuntu 24.04

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 menyusun ruang kerja @memmy/memory menjadi Memory/dist. Tiada bahagian lain dalam pepohon itu perlu dibina untuk pelayan tanpa antara muka grafik. Semak bahawa modul natif telah dimuatkan:

node -e "require('better-sqlite3'); console.log('better-sqlite3 loads')"

Jika baris itu menghasilkan ralat dan bukannya mencetak output, modul natif tersebut tidak sepadan dengan versi Node anda. Jalankan npm rebuild better-sqlite3, iaitu tindakan yang sama dilakukan oleh skrip mula projek itu sendiri sebelum melancarkan apa-apa.

README mendokumenkan bash scripts/dev-start.sh sebagai arahan mula tunggal. Jangan jalankannya pada VPS tanpa antara muka grafik. Arahan itu memulakan shell desktop Electron dan pelayan pembangunan Vite pada port 19000 bersama-sama perkhidmatan memori. Electron memerlukan paparan. Oleh itu, pada pelayan tanpa sesi grafik, skrip itu tersekat atau keluar.

Mulakan perkhidmatan memori dan semak bahawa ia memberikan respons

npm run memory:serve:dev

Itulah cara yang didokumenkan untuk menjalankan perkhidmatan memori daripada kod sumber. Perkhidmatan ini mengikat 127.0.0.1:18960, menyimpan pangkalan data di ~/.memmy/memory-service/memory.sqlite, dan membaca konfigurasi daripada ~/.memmy/config.yaml. README menyatakan nilai yang sama secara jelas apabila anda memerlukannya:

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

Daripada shell kedua, tanya perkhidmatan sama ada ia masih hidup:

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

Health ialah satu-satunya endpoint yang tidak pernah meminta token. Oleh itu, endpoint ini sesuai digunakan sebagai probe. Jika curl keluar dengan kod 7 dan mesej Failed to connect to 127.0.0.1 port 18960, tiada apa-apa yang sedang mendengar. Baca terminal yang menjalankan perkhidmatan itu kerana kegagalan semasa permulaan akan dicetak di situ. Punca lazimnya ialah modul SQLite natif gagal dimuatkan. ss -lntp | grep 18960 mengesahkan soket selepas perkhidmatan berjaya dimulakan.

API HTTP (antara muka pengaturcaraan aplikasi) yang lain berada di bawah /api/v1.

POST /api/v1/memory/add menulis memori dan POST /api/v1/memory/search membuat pertanyaan.
GET /api/v1/memory/:id dan DELETE /api/v1/memory/:id membaca serta membuang satu entri.
POST /api/v1/sessions/open dan POST /api/v1/sessions/:sessionId/close menandakan permulaan dan pengakhiran sesi ejen.
POST /api/v1/turns/start dan POST /api/v1/turns/:turnId/complete merekodkan satu giliran.
GET /api/v1/panel/overview, /api/v1/panel/analysis dan /api/v1/panel/items membekalkan data kepada papan pemuka.

Memmy memperuntukkan satu blok port. Dalam mod tanpa kepala, anda hanya menggunakan port pertama bagi setiap fungsi: 18960 untuk memori, 18970 untuk health gateway, 18980 untuk UI web dan HTTP pentadbiran, 18990 untuk API yang serasi dengan OpenAI dan dimulakan oleh memmy serve, kemudian 19000 dan 19010 untuk pelayan pembangunan frontend desktop. Jika sesuatu pada komputer anda telah menggunakan salah satu port tersebut, semak senarai ini.

Asal sebenar perintah memmy-memory

Di sinilah pemasangan pertama biasanya tersilap, jadi baca maklumat ini daripada pakej dan jangan membuat andaian. Nama perintah ini tiada kaitan dengan nama repositori. Perintah ini berasal daripada medan bin bagi ruang kerja yang mentakrifkannya:

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

Perintah itu mencetak {"memmy-memory":"./dist/src/cli/index.js"}. Jadi, titik masuk yang dibina ialah Memory/dist/src/cli/index.js, dan fail itu hanya wujud selepas npm run memory:build, kerana proses binaan mencipta dist serta menandakan fail itu sebagai boleh laku. Jalankan fail itu secara langsung:

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

Jika anda mahu nama ringkas itu tersedia dalam PATH, pautkan fail yang sama:

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

CLI menggunakan http://127.0.0.1:18960 secara lalai dan menerima --url, --token, --config, --source dan --user-id. Subperintahnya ialah init, health, search, add, get dan delete, serta panggilan sesi dan giliran yang digunakan oleh ejen, bukan oleh pengguna. memmy-memory search "deploy steps" dan memmy-memory add "staging migrates on deploy" ialah dua perintah yang paling kerap dijalankan oleh ejen.

Bagaimanakah anda menyambungkan Claude Code kepada Memmy?

Claude Code tidak mempunyai antara muka pemalam memori, jadi Memmy tidak disepadukan secara langsung dengannya. Penyepaduannya lebih mudah daripada itu. Claude Code menjalankan memmy-memory sebagai perintah shell biasa, dan fail arahan memberitahunya bila perintah itu perlu dijalankan. Pemasang Memmy yang didokumenkan menulis fail tersebut untuk anda: memmy-memory init --agent meletakkan fail arahan memori ke dalam direktori peraturan ejen sasaran.

Tulis arahan itu sendiri sekali supaya anda mengetahui dengan tepat perkara yang diarahkan kepada ejen. Claude Code membaca CLAUDE.md daripada punca projek pada permulaan setiap sesi. Oleh itu, bahagian seperti ini sudah memadai untuk keseluruhan penyepaduan:

## 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.

Jelaskan perkara yang diperoleh daripada pendekatan ini. Ini ialah penyepaduan pada peringkat arahan. Oleh itu, ia berfungsi apabila model memutuskan untuk menjalankan perintah tersebut, dan tidak sebaliknya. Tiada apa-apa yang memaksa panggilan itu dibuat. Jika sesi berakhir tanpa add, tiada apa-apa yang disimpan. Satu-satunya petunjuk ialah hasil kosong pada kali seterusnya anda membuat carian. Ini ialah pertukaran yang sama seperti fail memori Claude Code sendiri, dengan satu perbezaan: stor tersebut dikongsi. Oleh itu, nota itu turut tersedia kepada Codex dan Cursor pada mesin yang sama.

Arah yang satu lagi tidak memerlukan sebarang persediaan. Pengimbas Memmy sudah membaca ~/.claude/projects/**/*.jsonl, iaitu lokasi Claude Code menulis transkrip sesinya. Jalankan Memmy pada pelayan yang sama dengan pelayan tempat anda menjalankan Claude Code dalam sesi tmux, dan kerja semalam menjadi memori tanpa sebarang konfigurasi tambahan.

Adakah Memmy berfungsi sebagai pelayan MCP untuk Claude Code?

Tidak. Mengetahui arah sambungan ini dapat menjimatkan masa. MCP (protokol konteks model) mempunyai klien dan pelayan. Memmy ialah klien. Memmy bersambung ke pelayan MCP dan menyediakan alatnya kepada masa jalan ejennya sendiri. Memmy tidak menerbitkan titik akhir MCP yang boleh disambungkan oleh claude mcp add. Satu-satunya jambatan MCP dalam repositori ini ialah milik penyepaduan Composio dalam API tempatan desktop. API itu mengikat port rawak pada 127.0.0.1 di sebalik pengepala x-memmy-mcp-token sendiri.

Bahagian klien dikonfigurasikan dalam ~/.memmy/config.yaml, iaitu fail yang dirujuk oleh MEMMY_CONFIG, di bawah tools.mcpServers:

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

type menerima stdio, sse dan streamableHttp. Pelayan stdio berjalan sebagai proses anak Memmy. Oleh itu, perintahnya mesti wujud pada komputer yang sama dan berjalan sebagai pengguna yang sama. Jika anda sudah menjalankan pelayan MCP pada VPS, senaraikan pelayan tersebut di sini.

Memastikan stor memori kekal peribadi

Semua yang dimiliki Memmy berada di bawah ~/.memmy: config.yaml, ruang kerja, memory-service/memory.sqlite dan fail masa jalan. Pengimbasan dan pengingesan berlaku secara setempat, dan memori ditulis ke fail SQLite setempat itu. Oleh itu, tetapan lalai benar-benar bersifat setempat.

Dua laluan mengakses rangkaian. MEMMY_CLOUD_SERVICE ditetapkan kepada https://memmy-api.memtensor.cn secara lalai dan menyokong mod akaun dengan token percubaannya, jadi mod kunci API tidak pernah memanggilnya. Program penambahbaikan memori ialah togol berasingan dalam tetapan privasi dan kekal dimatikan sehingga anda menghidupkannya.

Laluan ketiga lebih mudah terlepas pandang. Jika anda mengkonfigurasi penyedia embedding berhos, teks setiap memori dihantar kepada penyedia itu supaya dapat ditukar menjadi vektor. Penyimpanan setempat tidak membantu dalam keadaan ini. Endpoint embedding yang anda hos sendiri ialah satu-satunya cara untuk menutup laluan tersebut.

Kekalkan port 18960 pada alamat loopback. Ia tidak memerlukan peraturan firewall kerana perkhidmatan yang terikat pada 127.0.0.1 langsung tidak boleh dicapai dari luar mesin. Aksesnya dari komputer riba anda melalui SSH:

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

Jika anda mengikatnya pada alamat yang lebih luas, tetapkan token terlebih dahulu. Menetapkan storage.token dalam konfigurasi, atau pemboleh ubah persekitaran MEMMY_MEMORY_TOKEN atau MEMORY_SERVICE_TOKEN, menyebabkan setiap endpoint kecuali health memerlukan token bearer. Nilai konfigurasi menyokong rujukan ${ENV_NAME}, jadi token dan kunci API model anda kekal di luar fail itu. Amalan ini sama seperti menyimpan rahsia di luar ejen AI di tempat lain, manakala dasar ufw default deny menjadi perlindungan tambahan jika versi akan datang mengubah alamat bind lalainya.

Sandarkan ~/.memmy sebelum anda mempercayainya

memory.sqlite ialah keseluruhan stor. Vektor disimpan dalam fail yang sama melalui sambungan sqlite-vec, jadi satu fail itu ialah sandaran. Menyalinnya dengan cp semasa perkhidmatan sedang menulis boleh menghasilkan pangkalan data yang tidak lengkap. Gunakan perintah sandaran SQLite sendiri:

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

Perintah itu menghasilkan salinan yang konsisten semasa perkhidmatan terus berjalan. Hantar salinan itu ke luar pelayan mengikut jadual, seperti yang dilakukan oleh restic ke storan luar tapak. Kehilangan config.yaml menyebabkan anda perlu memasukkan semula tetapan pembekal. Kehilangan memory.sqlite menyebabkan semua memori anda hilang, dan tiada salinan kedua disimpan di tempat lain pada mesin itu.

Jalankan perkhidmatan memory di bawah systemd

npm run memory:serve:dev dalam shell akan terhenti apabila shell ditutup. Fail unit memastikan perkhidmatan terus berjalan selepas but semula.

[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

Jangan letakkan token dalam unit. Simpan token dalam /etc/memmy/memory.env, dengan pemilikan root dan mod 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 dalam output status bermaksud systemd tidak dapat menjalankan ExecStart langsung. Oleh itu, semak which npm: lokasinya ialah /usr/bin/npm dalam pemasangan NodeSource dan sesuatu di bawah direktori utama pengguna bagi nvm, yang tidak akan ditemui oleh systemd. Unit yang bermula dan terus keluar gagal dalam npm. journalctl -u memmy-memory -n 50 memaparkan sebabnya. Mekanismenya sama seperti mana-mana perkhidmatan systemd lain pada VPS.

Perkara yang belum dilakukan oleh Memmy

Tiada binaan desktop Linux. Skrip pembungkusan meliputi macOS dan Windows, jadi workbench, wizard onboarding dan papan pemuka memori tidak tersedia pada pelayan itu sendiri.
memory:serve:dev menjalankan titik masuk TypeScript melalui tsx, iaitu laluan pembangunan. Repositori turut menyediakan memory:serve untuk output yang dikompil. Jalankan npm run tanpa argumen untuk melihat skrip yang sebenarnya tersedia dalam checkout anda.
Proses mendapatkan semula membina tetingkap carian daripada 2,000 baris vektor terkini, kemudian menggunakan pemilihan Top-K dalam tetingkap itu. Dalam stor yang sangat besar, memori lama mungkin berada di luar tetingkap tersebut.
Pembenaman berlaku selepas penangkapan, dan kegagalan dimasukkan ke dalam baris gilir percubaan semula, bukannya menyekat giliran ejen. Memori yang baru ditambah mungkin belum boleh ditemui melalui carian vektor.
Satu fail SQLite bermaksud satu nod. Tiada pengelompokan, jadi pelayan kedua mempunyai memori berasingan.

Versi 1.0.4 dan kira-kira 329 bintang pada July 2026 menunjukkan bahawa projek ini masih baharu. Flag, laluan dan nama skrip berubah antara keluaran. Baca medan bin dan output npm run dalam checkout anda sendiri, bukannya mempercayai arahan yang disalin dari mana-mana sumber, termasuk di sini.

FAQ

Mengapakah pemeriksaan kesihatan mengembalikan ralat sambungan ditolak?

Tiada proses mendengar pada port 18960. Kod keluar curl 7 dengan Failed to connect to 127.0.0.1 port 18960 bermaksud perkhidmatan memori tidak berjalan atau terhenti semasa permulaan. Oleh itu, baca output terminal atau jurnal di lokasi perkhidmatan tersebut dimulakan. Dua punca yang lazim ialah modul natif better-sqlite3 yang tidak sepadan dengan versi Node anda, yang boleh diperbaiki dengan npm rebuild better-sqlite3, dan versi Node yang lebih rendah daripada 22. Sahkan soket dengan ss -lntp | grep 18960 selepas perkhidmatan berjalan.

Dari manakah datangnya perintah `memmy-memory` selepas binaan daripada kod sumber?

Perintah itu datang daripada medan bin dalam pakej ruang kerja @memmy/memory, bukan daripada nama repositori. Jalankan node -p "JSON.stringify(require('./Memory/package.json').bin)" dalam checkout dan perintah itu akan mencetak {"memmy-memory":"./dist/src/cli/index.js"}. Fail tersebut hanya wujud selepas npm run memory:build kerana binaan mencipta dist dan menandakan fail itu sebagai boleh laksana. Jalankannya sebagai node Memory/dist/src/cli/index.js health, atau buat symlink kepadanya dalam /usr/local/bin untuk nama ringkas.

Bolehkah saya menambahkan Memmy pada Claude Code dengan `claude mcp add`?

Tidak. Memmy ialah klien MCP, bukan pelayan MCP. Memmy membuat sambungan keluar kepada pelayan yang disenaraikan di bawah tools.mcpServers dalam ~/.memmy/config.yaml dan menyediakan alat pelayan tersebut kepada runtime sendiri. Claude Code mencapai Memmy melalui kaedah yang bertentangan, iaitu dengan menjalankan CLI memmy-memory sebagai perintah shell berdasarkan fail arahan yang memmy-memory init --agent tulis dalam direktori peraturan ejen.

Adakah menjalankan Memmy menghantar memori saya kepada perkhidmatan awan?

Pengimbasan dan pengingesan berjalan secara setempat, dan memori ditulis ke ~/.memmy/memory-service/memory.sqlite pada cakera anda sendiri. MEMMY_CLOUD_SERVICE merujuk kepada https://memmy-api.memtensor.cn untuk mod akaun dan token percubaan, manakala program penambahbaikan memori kekal dinyahaktifkan sehingga anda mengaktifkannya. Komponen yang perlu dipantau ialah penyedia embedding: model embedding terhos menerima teks setiap memori yang ditukarkannya kepada vektor. Oleh itu, gunakan endpoint yang anda kendalikan sendiri jika perkara itu penting.

#memmy#memory #ai-agents #mcp #self-hosted