Panduan

Oleh Matt Connor 2026-07-31 · Diperbarui 2026-08-01

Memmy: Memori Lokal Bersama untuk Agen AI di VPS

Q: Dari mana perintah memmy-memory berasal setelah membangun dari kode sumber?

Perintah tersebut berasal dari kolom bin pada paket workspace @memmy/memory, bukan dari nama repositori. Jalankan node -p "JSON.stringify(require('./Memory/package.json').bin)" di dalam checkout. Perintah tersebut menampilkan {"memmy-memory":"./dist/src/cli/index.js"}. File itu hanya ada setelah npm run memory:build, karena proses build membuat dist dan menandai file tersebut sebagai executable. Jalankan file itu sebagai node Memory/dist/src/cli/index.js health, atau buat symlink ke /usr/local/bin untuk nama singkatnya.

Pelajari cara membangun Memmy 1.0.4 dari source di Ubuntu, menjalankan layanan pada port 18960, dan menyimpan catatan agen tetap lokal dalam satu database SQLite.

Memmy dan data yang disimpannya

Memmy adalah pusat memori lokal untuk agen AI yang berjalan di VPS (virtual private server) milik Anda. Memmy menyimpan satu database SQLite berisi hal-hal yang telah dipelajari agen Anda. Semua agen di server tersebut membaca dan menulis ke penyimpanan yang sama. Proyek ini memmy-agent dari MemTensor, berlisensi MIT, dan berada pada versi 1.0.4 per Juli 2026.

Hanya sebagian fiturnya yang relevan di server. Memmy menyediakan layanan memori yang mendengarkan pada http://127.0.0.1:18960, antarmuka baris perintah (CLI) memmy-memory yang berkomunikasi dengan layanan tersebut, serta workbench desktop. Workbench hanya dikemas untuk macOS dan Windows. Jadi, pada VPS Linux, Anda menjalankan layanan dan CLI. Konfigurasi ini cukup untuk menyediakan memori bersama bagi Claude Code, Codex, dan Cursor.

Memmy mengelompokkan data yang disimpannya ke dalam empat lapisan. L1 Trace adalah giliran mentah yang berisi permintaan, respons, dan pemanggilan alat. L2 Policy adalah prosedur yang diturunkan dari trace dan terbukti berguna. L3 World Model adalah pengetahuan stabil tentang proyek atau lingkungan. Skill adalah prosedur yang dapat dipanggil dan dibentuk dari policy. Layanan menetapkan lapisan saat memasukkan sebuah giliran, sehingga Anda tidak perlu membuatnya secara manual.

Perubahan yang dibawa hub memori bersama dibandingkan dengan memori per alat

Saat ini, setiap agen merilis sistem memorinya sendiri. Claude Code menyimpan file instruksi di repositori. Cursor menyimpan aturan di basis data ruang kerjanya. Codex menyimpan log sesi di bawah ~/.codex. Setiap penyimpanan hanya digunakan oleh satu alat. Karena itu, fakta yang Anda ajarkan pada hari Senin di satu alat tidak diketahui oleh alat lain pada hari Selasa. Anda membayar dua kali untuk kondisi ini: pertama, melalui token yang digunakan untuk menjelaskan ulang proyek yang sama; kedua, melalui pekerjaan yang keliru ketika agen bertindak berdasarkan asumsi yang sudah Anda koreksi di tempat lain.

Hub memindahkan penyimpanan tersebut keluar dari alat. Memmy juga membaca penyimpanan yang sudah ada, sehingga Anda tidak perlu memulai dari basis data kosong. Pemindainya 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, file state.vscdb milik Cursor, basis data SQLite OpenClaw di bawah ~/.openclaw, dan Hermes di bawah ~/.hermes. Anda dapat menambahkan sumber secara manual menggunakan nama dan path lokal.

Jumlah yang diimpor tidak akan sama, dan hal itu memang diharapkan. Pemindai mengelompokkan pesan berdasarkan sumber dan percakapan, lalu menulis satu memori L1 untuk setiap giliran lengkap. Sebuah giliran dianggap lengkap jika berisi konten pengguna yang tidak kosong dan diakhiri pesan asisten yang tidak kosong. Dengan demikian, sesi yang terputus tidak menyumbang apa pun. Pesan dideduplikasi menggunakan checkpoint percakapan dan ID giliran yang stabil. Jumlah yang dipindai, jumlah pesan yang diimpor, dan jumlah memori baru akan berbeda dalam proses yang sama.

Bagian ini melengkapi cara Claude Code mengelola konteks dalam satu sesi. Manajemen konteks menentukan hal yang dapat dimuat dalam satu jendela. Hub memori menentukan hal yang tetap tersedia setelah jendela tersebut ditutup.

Yang Anda perlukan di VPS

Node.js 22 atau yang lebih baru. Dokumentasi Memmy mensyaratkannya, sedangkan Ubuntu 24.04 merilis Node 18.
git dan toolchain build, karena better-sqlite3 adalah modul native yang mungkin dikompilasi saat instalasi.
RAM sekitar 2 GB. Instalasi root mengambil workspace besar dan toolchain build frontend.
Ruang disk kosong beberapa GB untuk node_modules dan database.

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 harus menampilkan v22 atau yang lebih tinggi. Nilai v18 di sini berarti langkah NodeSource tidak berhasil, dan instalasi nantinya gagal saat pemeriksaan engine proyek.

Instal Memmy dari source di 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 mengompilasi workspace @memmy/memory menjadi Memory/dist. Tidak ada bagian lain dalam tree yang perlu dibuat untuk server headless. Pastikan modul native berhasil dimuat:

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

Jika baris tersebut menghasilkan error, bukan mencetak output, berarti modul native tidak cocok dengan versi Node Anda. Jalankan npm rebuild better-sqlite3. Perintah ini sama persis dengan yang dijalankan oleh skrip start milik proyek sebelum memulai proses apa pun.

README mendokumentasikan bash scripts/dev-start.sh sebagai perintah untuk memulai semuanya. Jangan jalankan perintah tersebut pada VPS headless. Perintah itu memulai shell desktop Electron dan server pengembangan Vite pada port 19000 bersama layanan memori. Electron memerlukan display. Karena itu, pada server tanpa sesi grafis, skrip tersebut akan berhenti atau keluar.

Mulai layanan memori dan periksa responsnya

npm run memory:serve:dev

Itulah cara yang didokumentasikan untuk menjalankan layanan memori dari kode sumber. Layanan ini mengikat 127.0.0.1:18960, menyimpan database di ~/.memmy/memory-service/memory.sqlite, dan membaca konfigurasi dari ~/.memmy/config.yaml. README mencantumkan nilai yang sama secara eksplisit:

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

Dari shell kedua, tanyakan apakah layanan masih aktif:

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

Health adalah satu-satunya endpoint yang tidak pernah meminta token. Karena itu, endpoint ini merupakan probe yang tepat. Jika curl keluar dengan kode 7 dan pesan Failed to connect to 127.0.0.1 port 18960, tidak ada proses yang sedang mendengarkan. Periksa terminal tempat layanan berjalan, karena crash saat startup ditampilkan di sana. Penyebab yang umum adalah modul SQLite native gagal dimuat. ss -lntp | grep 18960 mengonfirmasi socket setelah layanan aktif.

Sisa HTTP API (antarmuka pemrograman aplikasi) berada di bawah /api/v1.

POST /api/v1/memory/add menulis memori, sedangkan POST /api/v1/memory/search melakukan kueri.
GET /api/v1/memory/:id dan DELETE /api/v1/memory/:id membaca serta menghapus satu entri.
POST /api/v1/sessions/open dan POST /api/v1/sessions/:sessionId/close mengapit sesi agen.
POST /api/v1/turns/start dan POST /api/v1/turns/:turnId/complete mencatat satu giliran.
GET /api/v1/panel/overview, /api/v1/panel/analysis, dan /api/v1/panel/items memasukkan data ke dasbor.

Memmy menetapkan blok port. Dalam penggunaan tanpa antarmuka, Anda hanya menggunakan port pertama: 18960 untuk memori, 18970 untuk health gateway, 18980 untuk UI web dan HTTP admin, 18990 untuk API yang kompatibel dengan OpenAI yang dimulai oleh memmy serve, kemudian 19000 dan 19010 untuk server pengembangan frontend desktop. Jika salah satu port tersebut sudah digunakan di komputer Anda, periksa daftar itu.

Dari mana perintah memmy-memory sebenarnya berasal

Di sinilah instalasi pertama biasanya gagal. Baca informasinya dari paket, bukan berdasarkan perkiraan. Nama perintah tidak berkaitan dengan nama repositori. Nama tersebut berasal dari kolom bin pada workspace yang mendefinisikannya:

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

Perintah tersebut menampilkan {"memmy-memory":"./dist/src/cli/index.js"}. Jadi, titik masuk yang telah dibangun adalah Memory/dist/src/cli/index.js. Titik masuk ini hanya ada setelah npm run memory:build, karena proses build membuat dist dan menandai file tersebut sebagai executable. Jalankan secara langsung:

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

Jika ingin menggunakan nama singkat pada PATH, buat tautan ke file 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 default dan menerima --url, --token, --config, --source, dan --user-id. Subperintahnya adalah init, health, search, add, get, dan delete, serta pemanggilan sesi dan turn yang digunakan oleh agen, bukan oleh pengguna. memmy-memory search "deploy steps" dan memmy-memory add "staging migrates on deploy" adalah dua perintah yang paling sering dijalankan oleh agen.

Bagaimana cara menghubungkan Claude Code ke Memmy?

Claude Code tidak memiliki antarmuka plugin memori, jadi Memmy tidak terhubung langsung ke dalamnya. Integrasinya lebih sederhana. Claude Code menjalankan memmy-memory sebagai perintah shell biasa, dan file instruksi memberi tahu kapan perintah itu harus dijalankan. Penginstal Memmy yang terdokumentasi menulis file tersebut untuk Anda: memmy-memory init --agent menempatkan file instruksi memori ke dalam direktori aturan agen target.

Tulis instruksi tersebut secara manual satu kali agar Anda mengetahui dengan tepat instruksi yang diterima agen. Claude Code membaca CLAUDE.md dari root proyek pada awal setiap sesi, sehingga bagian seperti ini sudah mencakup seluruh integrasi:

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

Pahami batasannya. Ini adalah integrasi pada tingkat instruksi. Integrasi ini berfungsi ketika model memutuskan untuk menjalankan perintah tersebut, dan tidak berfungsi jika model tidak mengambil keputusan itu. Tidak ada mekanisme yang memaksa pemanggilan tersebut. Jika sesi berakhir tanpa add, tidak ada data yang disimpan. Satu-satunya indikasinya adalah hasil kosong saat Anda melakukan pencarian berikutnya. Ini merupakan kompromi yang sama seperti file memori bawaan Claude Code, dengan satu perbedaan: penyimpanannya digunakan bersama, sehingga catatan tersebut juga tersedia bagi Codex dan Cursor pada mesin yang sama.

Arah sebaliknya tidak memerlukan konfigurasi apa pun. Pemindai Memmy sudah membaca ~/.claude/projects/**/*.jsonl, yaitu lokasi Claude Code menulis transkrip sesinya. Jalankan Memmy pada server yang sama dengan server tempat Anda menjalankan Claude Code di dalam sesi tmux, dan pekerjaan kemarin akan menjadi memori tanpa konfigurasi tambahan.

Apakah Memmy berfungsi sebagai server MCP untuk Claude Code?

Tidak. Memahami arahnya dapat menghemat waktu. MCP (model context protocol) memiliki klien dan server. Memmy adalah klien. Memmy terhubung ke server MCP dan menyediakan alatnya untuk runtime agennya sendiri. Memmy tidak memublikasikan endpoint MCP yang dapat dituju oleh claude mcp add. Satu-satunya bridge MCP di repositori ini adalah milik integrasi Composio di dalam local API desktop. API tersebut melakukan bind ke port acak pada 127.0.0.1 dengan header x-memmy-mcp-token miliknya sendiri.

Sisi klien dikonfigurasi di ~/.memmy/config.yaml, yaitu file yang ditunjuk 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. Server stdio berjalan sebagai proses anak Memmy. Artinya, command tersebut harus tersedia di komputer yang sama dan berjalan sebagai user yang sama. Jika Anda sudah menjalankan server MCP di VPS, cantumkan server tersebut di sini.

Menjaga penyimpanan memori tetap privat

Semua yang dimiliki Memmy berada di bawah ~/.memmy: config.yaml, ruang kerja, memory-service/memory.sqlite, dan file runtime. Pemindaian dan penyerapan berlangsung secara lokal, lalu memori ditulis ke file SQLite lokal tersebut. Dengan demikian, konfigurasi default benar-benar bersifat lokal.

Dua jalur memang mengakses jaringan. MEMMY_CLOUD_SERVICE secara default mengarah ke https://memmy-api.memtensor.cn dan mendukung mode akun dengan token uji cobanya. Karena itu, mode kunci API tidak pernah memanggilnya. Program peningkatan memori adalah pengaturan terpisah dalam pengaturan privasi dan tetap nonaktif sampai Anda mengaktifkannya.

Ada jalur ketiga yang lebih mudah terlewatkan. Jika Anda mengonfigurasi penyedia embedding yang di-host, teks setiap memori dikirim ke penyedia tersebut agar dapat diubah menjadi vektor. Penyimpanan lokal tidak mencegah hal itu. Endpoint embedding yang Anda host sendiri adalah satu-satunya cara untuk menutup jalur tersebut.

Pertahankan port 18960 pada alamat loopback. Port ini tidak memerlukan aturan firewall, karena layanan yang terikat ke 127.0.0.1 sama sekali tidak dapat diakses dari luar server. Akses layanan tersebut dari laptop melalui SSH:

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

Jika Anda mengikatnya ke alamat yang lebih luas, tetapkan token terlebih dahulu. Menetapkan storage.token dalam konfigurasi, atau variabel lingkungan MEMMY_MEMORY_TOKEN atau MEMORY_SERVICE_TOKEN, membuat semua endpoint selain health memerlukan bearer token. Nilai konfigurasi mendukung referensi ${ENV_NAME}, sehingga token dan kunci API model Anda tetap berada di luar file itu sendiri. Kebiasaan ini sama dengan menjaga rahasia tetap berada di luar agen AI di tempat lain, sedangkan kebijakan ufw default deny menjadi perlindungan cadangan jika versi mendatang mengubah alamat bind default-nya.

Cadangkan ~/.memmy sebelum Anda mempercayainya

memory.sqlite adalah seluruh penyimpanan. Vektor tersimpan dalam file yang sama melalui ekstensi sqlite-vec, sehingga satu file tersebut menjadi cadangan. Menyalinnya dengan cp saat layanan sedang menulis dapat menghasilkan database yang rusak sebagian. Gunakan perintah pencadangan bawaan SQLite:

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

Perintah tersebut menghasilkan salinan yang konsisten saat layanan tetap berjalan. Kirim salinan itu ke luar server secara terjadwal. Itulah fungsi restic ke penyimpanan di luar server. Kehilangan config.yaml hanya mengharuskan Anda memasukkan ulang pengaturan penyedia. Kehilangan memory.sqlite berarti kehilangan semua memori, dan tidak ada salinan kedua di mesin tersebut.

Jalankan layanan memori dengan systemd

npm run memory:serve:dev dalam shell akan berhenti saat shell berhenti. File unit menjaga layanan tetap berjalan setelah reboot.

[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 simpan token di dalam unit. Simpan token di /etc/memmy/memory.env, dengan pemilik root dan mode 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 pada keluaran status berarti systemd sama sekali tidak dapat menjalankan ExecStart. Karena itu, periksa which npm: pada instalasi NodeSource, jalurnya adalah /usr/bin/npm, sedangkan pada nvm jalurnya berada di suatu tempat di direktori home pengguna, yang tidak akan ditemukan oleh systemd. Unit yang mulai lalu langsung berhenti mengalami kegagalan di dalam npm. journalctl -u memmy-memory -n 50 menampilkan penyebabnya. Mekanismenya sama seperti layanan systemd lainnya di VPS.

Hal yang Belum Dapat Dilakukan Memmy

Belum ada build desktop Linux. Skrip packaging mencakup macOS dan Windows, sehingga workbench, wizard onboarding, dan dasbor memori tidak tersedia langsung di server.
memory:serve:dev menjalankan entry point TypeScript melalui tsx, yaitu jalur pengembangan. Repository juga menyediakan memory:serve untuk output terkompilasi. Jalankan npm run tanpa argumen untuk melihat skrip yang benar-benar tersedia di checkout Anda.
Retrieval membuat jendela pencarian dari 2,000 baris vektor terbaru, lalu menerapkan pemilihan Top-K di dalam jendela tersebut. Pada penyimpanan yang sangat besar, memori lama dapat berada di luar jendela itu.
Embedding dilakukan setelah capture, dan kegagalan masuk ke antrean retry, bukan menghentikan giliran agent. Memori yang baru saja ditambahkan mungkin belum dapat ditemukan melalui pencarian vektor.
Satu file SQLite berarti satu node. Tidak ada clustering, sehingga server kedua merupakan memori terpisah.

Versi 1.0.4 dan sekitar 329 stars per Juli 2026 menunjukkan bahwa proyek ini masih baru. Flag, path, dan nama skrip dapat berubah antar-rilis. Baca field bin dan output npm run di checkout Anda sendiri, bukan mengandalkan perintah yang disalin dari mana pun, termasuk dari sini.

FAQ

Mengapa pemeriksaan kesehatan mengembalikan penolakan koneksi?

Tidak ada proses yang mendengarkan pada port 18960. Kode keluar curl 7 dengan Failed to connect to 127.0.0.1 port 18960 berarti layanan memori tidak berjalan atau berhenti saat startup. Karena itu, baca terminal atau journal tempat layanan tersebut dimulai. Dua penyebab yang umum adalah modul native better-sqlite3 yang tidak cocok dengan versi Node Anda, yang diperbaiki dengan npm rebuild better-sqlite3, dan versi Node di bawah 22. Konfirmasikan socket dengan ss -lntp | grep 18960 setelah layanan berjalan.

Dari mana perintah `memmy-memory` berasal setelah membangun dari kode sumber?

Perintah tersebut berasal dari kolom bin pada paket workspace @memmy/memory, bukan dari nama repositori. Jalankan node -p "JSON.stringify(require('./Memory/package.json').bin)" di dalam checkout. Perintah tersebut menampilkan {"memmy-memory":"./dist/src/cli/index.js"}. File itu hanya ada setelah npm run memory:build, karena proses build membuat dist dan menandai file tersebut sebagai executable. Jalankan file itu sebagai node Memory/dist/src/cli/index.js health, atau buat symlink ke /usr/local/bin untuk nama singkatnya.

Dapatkah saya menambahkan Memmy ke Claude Code dengan `claude mcp add`?

Tidak. Memmy adalah klien MCP, bukan server MCP. Memmy terhubung ke server yang tercantum di bawah tools.mcpServers dalam ~/.memmy/config.yaml dan menyediakan tool server tersebut untuk runtime-nya sendiri. Claude Code mengakses Memmy dengan cara sebaliknya, yaitu menjalankan CLI memmy-memory sebagai perintah shell berdasarkan file instruksi yang memmy-memory init --agent tulis ke direktori aturan agent.

Apakah menjalankan Memmy mengirim memori saya ke layanan cloud?

Pemindaian dan ingestion berjalan secara lokal, dan memori ditulis ke ~/.memmy/memory-service/memory.sqlite pada disk Anda sendiri. MEMMY_CLOUD_SERVICE mengarah ke https://memmy-api.memtensor.cn untuk mode akun dan token uji coba. Program peningkatan memori tetap nonaktif sampai Anda mengaktifkannya. Hal yang perlu dipantau adalah penyedia embedding: model embedding yang di-host menerima teks setiap memori yang diubahnya menjadi vektor. Jadi, gunakan endpoint yang Anda jalankan sendiri jika hal itu penting bagi Anda.

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