Jinsi ya kuweka Memmy kwenye VPS kwa mawakala wa AI

Memmy ni nini na inahifadhi nini

Memmy ni kitovu cha kumbukumbu cha ndani kwa ajili ya mawakala wa AI kinachoendeshwa kwenye VPS (virtual private server) yako mwenyewe. Inatunza hifadhidata moja ya SQLite ya yale ambayo mawakala wako wamejifunza, na kila wakala kwenye seva hiyo husoma na kuandika kwenye hifadhi hiyo hiyo. Mradi huu ni memmy-agent kutoka MemTensor, una leseni ya MIT, na uko kwenye toleo la 1.0.4 kufikia Julai 2026.

Sehemu yake tu ndiyo muhimu kwenye seva. Memmy inatoa huduma ya kumbukumbu inayofanya kazi kwenye http://127.0.0.1:18960, kiolesura cha mstari wa amri (CLI) cha memmy-memory kinachowasiliana na huduma hiyo, na workbench ya desktop. Workbench imefungashwa kwa ajili ya macOS na Windows pekee, kwa hivyo kwenye Linux VPS unaendesha huduma hiyo na CLI. Hiyo inatosha kuipa Claude Code, Codex na Cursor kumbukumbu ya pamoja.

Memmy hupanga kile inachohifadhi katika matabaka manne. L1 Trace ni mwingiliano mbichi: ombi, jibu na wito wa zana. L2 Policy ni utaratibu uliotokana na mwingiliano ambao umethibitika kuwa na manufaa. L3 World Model ni maarifa thabiti kuhusu mradi au mazingira. Skill ni utaratibu unaoweza kuitwa ambao umekuzwa kutoka kwa sera. Huduma hiyo hupanga tabaka wakati inapopokea mwingiliano, kwa hivyo huziunda kwa mikono.

Jinsi kitovu cha kumbukumbu ya pamoja kinavyobadilisha kumbukumbu ya kila zana

Kila wakala kwa sasa husafirisha kumbukumbu yake yenyewe. Claude Code huweka faili za maelekezo ndani ya hazina. Cursor huweka sheria katika hifadhidata ya eneo-kazi lake. Codex huweka kumbukumbu za kikao chini ya ~/.codex. Kila hifadhi ni ya zana moja, kwa hivyo ukweli ulioufundisha siku ya Jumatatu katika zana moja haujulikani siku ya Jumanne katika nyingine. Unalipia hilo mara mbili: mara moja kwa tokeni zinazotumika kuelezea upya mradi uleule, na mara ya pili kwa kazi isiyo sahihi wakati wakala anapotenda kulingana na dhana uliyokwisha kurekebisha mahali pengine.

Kitovu huhamisha hifadhi kutoka kwenye zana. Memmy pia husoma hifadhi zilizopo, kwa hivyo huanzi na hifadhidata tupu. Kichanganuzi chake kinajua vyanzo sita: Claude Code katika ~/.claude/projects/**/*.jsonl, Codex katika ~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-*.jsonl, OpenCode katika ~/.local/share/opencode/opencode.db, faili za state.vscdb za Cursor, hifadhidata za SQLite za OpenClaw chini ya ~/.openclaw, na Hermes chini ya ~/.hermes. Unaweza kuongeza chanzo kwa mkono ukitumia jina na njia ya ndani.

Vihesabio vya kuingiza data havitalingana, na hilo linatarajiwa. Kichanganuzi hupanga ujumbe kulingana na chanzo na mazungumzo, kisha huandika kumbukumbu moja ya L1 kwa kila zamu kamili. Zamu huhesabiwa kuwa kamili wakati ina maudhui ya mtumiaji yasiyo tupu na kuishia na ujumbe wa msaidizi usio tupu, kwa hivyo kikao kilichokatizwa hakichangii chochote. Ujumbe huondolewa nakala rudufu kwa kutumia vituo vya ukaguzi vya mazungumzo na vitambulisho vya zamu thabiti. Hesabu iliyochanganuliwa, hesabu ya ujumbe ulioingizwa na hesabu ya kumbukumbu mpya zote hutofautiana katika utekelezaji mmoja.

Hii ndiyo sehemu inayooana na jinsi Claude Code inavyosimamia muktadha ndani ya kikao kimoja. Usimamizi wa muktadha huamua kile kinachotoshea katika dirisha moja. Kitovu cha kumbukumbu huamua kile kinachobaki baada ya dirisha hilo kufungwa.

Unachohitaji kwenye VPS

• Node.js 22 au mpya zaidi. Nyaraka za Memmy zinahitaji toleo hili, na Ubuntu 24.04 inakuja na Node 18.
• git na zana za ujenzi (build toolchain), kwa sababu better-sqlite3 ni moduli ya asili (native module) inayoweza kuhitaji kukusanywa (compile) wakati wa usakinishaji.
• Takriban 2 GB ya RAM. Usakinishaji wa root unavuta workspace kubwa na mnyororo wa ujenzi wa frontend.
• GB chache za nafasi ya diski kwa ajili ya node_modules na hifadhidata.

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 inapaswa kuonyesha v22 au zaidi. v18 hapa inamaanisha hatua ya NodeSource haikufanikiwa, na usakinishaji utafeli baadaye wakati wa ukaguzi wa injini ya mradi.

Kusakinisha Memmy kutoka kwenye chanzo (source) kwenye 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 huandaa (compile) workspace ya @memmy/memory kuwa Memory/dist. Hakuna kingine kwenye mti wa faili kinachohitajika kujengwa (build) kwa ajili ya seva isiyo na kiolesura (headless server). Hakikisha moduli ya asili (native module) imepakiwa:

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

Ikiwa mstari huo utatoa hitilafu badala ya kuchapisha matokeo, basi moduli ya asili hailingani na toleo lako la Node. Tekeleza npm rebuild better-sqlite3, ambayo ndiyo hasa script ya kuanzisha ya mradi huo hufanya kabla ya kuzindua chochote.

README inaelezea bash scripts/dev-start.sh kama amri moja ya kuanzisha. Usiitekeleze kwenye VPS isiyo na kiolesura. Inazindua shell ya desktop ya Electron na seva ya maendeleo ya Vite kwenye port 19000 kando ya huduma ya memory, na Electron inahitaji display. Kwa hivyo, kwenye seva isiyo na session ya picha (graphical session), script hiyo hukwama au kutoka.

Anzisha huduma ya memory na uhakikishe inajibu

npm run memory:serve:dev

Hiyo ndiyo njia iliyoelekezwa kwenye nyaraka ya kuendesha huduma ya memory kutoka kwenye source. Inajifunga kwenye 127.0.0.1:18960, inahifadhi database kwenye ~/.memmy/memory-service/memory.sqlite, na inasoma usanidi kutoka ~/.memmy/config.yaml. README inaeleza thamani hizo hizo unapotaka ziwe wazi:

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

Kutoka kwenye terminal ya pili, iulize huduma kama iko hai:

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

Health ndiyo endpoint pekee ambayo haiitaji token, ndiyo maana ndiyo probe sahihi. Ikiwa curl itatoka na code 7 na ujumbe wa Failed to connect to 127.0.0.1 port 18960, hakuna kinachosikiliza. Soma terminal inayoendesha huduma hiyo, kwa sababu crash wakati wa kuanza huchapishwa hapo, na sababu ya kawaida ni moduli ya SQLite kushindwa kupakia. ss -lntp | grep 18960 inathibitisha socket pindi huduma inapokuwa imewaka.

Sehemu nyingine ya HTTP API (application programming interface) iko chini ya /api/v1.

• POST /api/v1/memory/add inaandika memory na POST /api/v1/memory/search inatafuta (query).
• GET /api/v1/memory/:id na DELETE /api/v1/memory/:id inasoma na kufuta ingizo moja.
• POST /api/v1/sessions/open na POST /api/v1/sessions/:sessionId/close inafungua na kufunga session ya agent.
• POST /api/v1/turns/start na POST /api/v1/turns/:turnId/complete inarekodi zamu moja.
• GET /api/v1/panel/overview, /api/v1/panel/analysis na /api/v1/panel/items inalisha dashboard.

Memmy inatenga kundi la port, na ukiwa huna kiolesura (headless) unatumia ya kwanza pekee: 18960 kwa ajili ya memory, 18970 kwa ajili ya gateway health, 18980 kwa ajili ya web UI na admin HTTP, 18990 kwa ajili ya API inayooana na OpenAI ambayo memmy serve inaiwasha, kisha 19000 na 19010 kwa ajili ya dev server ya desktop frontend. Ikiwa kuna kitu kwenye seva yako kinatumia mojawapo ya port hizo, orodha hiyo ndiyo mahali pa kuangalia.

Mahali ambapo amri ya memmy-memory inapotokea

Hapa ndipo usakinishaji wa kwanza unapokwama mara nyingi, kwa hivyo isome kutoka kwenye kifurushi badala ya kukisia. Jina la amri halina uhusiano wowote na jina la hazina (repository). Inatoka kwenye sehemu ya bin ya workspace inayoiainisha:

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

Hiyo huchapisha {"memmy-memory":"./dist/src/cli/index.js"}. Kwa hivyo, sehemu ya kuingilia (entry point) iliyojengwa ni Memory/dist/src/cli/index.js, na inapatikana tu baada ya npm run memory:build, kwa sababu ujenzi (build) ndio unaounda dist na kuweka faili hiyo iweze kutekelezeka (executable). Iendeshe moja kwa moja:

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

Ikiwa unataka jina fupi kwenye PATH yako, unganisha (link) faili hiyo hiyo:

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

CLI hii hutumia http://127.0.0.1:18960 kama chaguo-msingi na inakubali --url, --token, --config, --source na --user-id. Amri zake ndogo (subcommands) ni init, health, search, add, get na delete, pamoja na wito wa session na turn ambao hutumiwa na mawakala (agents) badala ya watu. memmy-memory search "deploy steps" na memmy-memory add "staging migrates on deploy" ndizo mbili ambazo wakala huendesha mara nyingi zaidi.

Unaunganishaje Claude Code na Memmy?

Claude Code haina kiolesura cha plugin ya kumbukumbu, kwa hivyo Memmy haiunganishwi nayo moja kwa moja. Ujumuishaji wake ni rahisi zaidi ya hapo. Claude Code huendesha memmy-memory kama amri ya kawaida ya shell, na faili la maelekezo humwambia wakati wa kufanya hivyo. Kisakinishi kilichoorodheshwa cha Memmy hukuandikia faili hilo: memmy-memory init --agent huweka faili la maelekezo ya kumbukumbu kwenye saraka ya sheria za wakala husika.

Andika maelekezo hayo kwa mkono mara moja, kwa sababu utajua hasa kile ambacho wakala aliambiwa. Claude Code husoma CLAUDE.md kutoka kwenye mzizi wa mradi mwanzoni mwa kila kipindi, kwa hivyo sehemu kama hii ndiyo ujumuishaji mzima:

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

Kuwa wazi kuhusu faida unayopata. Huu ni ujumuishaji wa kiwango cha maelekezo, kwa hivyo hufanya kazi wakati modeli inapoamua kuendesha amri hiyo, na si vinginevyo. Hakuna kinacholazimisha wito huo. Ikiwa kipindi kitaisha bila add, hakuna kilichohifadhiwa, na ishara pekee ni matokeo matupu wakati mwingine utakapofanya utafutaji. Hiyo ni biashara sawa na faili za kumbukumbu za Claude Code zenyewe, kwa tofauti moja: hifadhi inashirikiwa, kwa hivyo dokezo hilo pia huwafikia Codex na Cursor kwenye mashine hiyo hiyo.

Upande mwingine hauhitaji usanidi wowote. Kichanganuzi cha Memmy tayari husoma ~/.claude/projects/**/*.jsonl, ambapo Claude Code huandika nakala za vipindi vyake. Endesha Memmy kwenye seva hiyo hiyo unayoendesha Claude Code ndani ya kipindi cha tmux na kazi ya jana inakuwa kumbukumbu bila wewe kusanidi chochote.

Je, Memmy inafanya kazi kama seva ya MCP kwa ajili ya Claude Code?

Hapana, na kufahamu mwelekeo huu kutakuokoa muda mwingi. MCP (model context protocol) ina wateja (clients) na seva. Memmy ni mteja. Huunganisha kwenye seva za MCP na kutoa zana zake kwa runtime ya wakala wake. Haichapishi endpoint ya MCP ambayo claude mcp add inaweza kuelekezwa kwayo. Daraja pekee la MCP katika hazina hii ni lile la ushirikiano wa Composio ndani ya API ya ndani ya desktop, na API hiyo hufunga port ya nasibu kwenye 127.0.0.1 nyuma ya header yake yenyewe ya x-memmy-mcp-token.

Upande wa mteja umesanidiwa katika ~/.memmy/config.yaml, faili ambalo MEMMY_CONFIG linaelekeza kwalo, chini ya tools.mcpServers:

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

type inakubali stdio, sse na streamableHttp. Seva ya stdio huendeshwa kama mchakato mtoto (child process) wa Memmy, jambo linalomaanisha kuwa amri yake lazima iwepo kwenye mashine hiyo hiyo na iendeshwe na mtumiaji yule yule. Ikiwa tayari unadumisha seva za MCP zinazoendeshwa kwenye VPS, hizo ndizo unazopaswa kuziorodhesha hapa.

Kuweka hifadhi ya kumbukumbu kuwa ya faragha

Kila kitu kinachomilikiwa na Memmy kipo chini ya ~/.memmy: config.yaml, workspace, memory-service/memory.sqlite na faili za runtime. Uchanganuzi na uingizaji wa data hufanyika ndani ya kifaa (locally), na kumbukumbu huandikwa kwenye faili hiyo ya SQLite ya ndani, kwa hivyo hali ya kawaida ni ya faragha kabisa.

Njia mbili hufikia mtandao. MEMMY_CLOUD_SERVICE kwa kawaida hutumia https://memmy-api.memtensor.cn na huwezesha hali ya akaunti (account mode) kwa kutumia token za majaribio, kwa hivyo hali ya API key haijawahi kuitumia. Programu ya kuboresha kumbukumbu ni swichi tofauti katika mipangilio ya faragha, ambayo imezimwa hadi utakapoiwasha.

Njia ya tatu ni rahisi kusahaulika. Ukisanidi mtoa huduma wa embedding anayehifadhiwa kwenye seva ya mbali (hosted embedding provider), maandishi ya kila kumbukumbu hutumwa kwa mtoa huduma huyo ili yaweze kugeuzwa kuwa vector. Hifadhi ya ndani haisaidii katika hali hiyo. Endpoint ya embedding unayojiendeshea mwenyewe ndiyo njia pekee ya kufunga njia hiyo.

Weka port 18960 kwenye loopback address. Haihitaji sheria yoyote ya firewall, kwa sababu huduma iliyofungwa kwenye 127.0.0.1 haiwezi kufikiwa kutoka nje ya seva hata kidogo. Ifikie kutoka kwenye laptop yako kupitia SSH badala yake:

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

Ikiwa utaifunga kwa upana zaidi wakati wowote, weka token kwanza. Kuweka storage.token kwenye config, au kutumia variable ya mazingira ya MEMMY_MEMORY_TOKEN au MEMORY_SERVICE_TOKEN, hufanya kila endpoint isipokuwa ya afya (health) kuhitaji bearer token. Thamani za config zinaunga mkono marejeleo ya ${ENV_NAME}, kwa hivyo token na API keys za model yako hubaki nje ya faili yenyewe. Hiyo ni tabia sawa na kuweka siri nje ya AI agents kwingineko, na sera ya uzuiaji wa default ya ufw ni kinga yako ya mwisho ikiwa toleo la baadaye litabadilisha anwani yake ya default ya bind.

Hifadhi nakala ya ~/.memmy kabla ya kuitegemea

memory.sqlite ndiyo hifadhi nzima. Vektari hukaa kwenye faili hilo hilo kupitia kiendelezi cha sqlite-vec, kwa hivyo faili moja ndilo hifadhi nakala. Kunakili faili hilo kwa cp wakati huduma inaandika data kunaweza kusababisha database kuharibika. Tumia amri ya hifadhi nakala ya SQLite yenyewe:

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

Hii hutengeneza nakala thabiti wakati huduma ikiwa inaendelea kufanya kazi. Ihamishe kutoka kwenye seva hiyo kwa ratiba maalum, jambo ambalo ndilo kusudi la restic kwenda kwenye hifadhi ya nje. Kupoteza config.yaml kunakugharimu mipangilio ya mtoa huduma ambayo unaweza kuandika upya. Kupoteza memory.sqlite kunakugharimu kila kumbukumbu, na hakuna kitu kingine kwenye mashine hiyo kinachoshikilia nakala ya pili.

Endesha huduma ya kumbukumbu chini ya systemd

npm run memory:serve:dev katika shell hufa shell inapofungwa. Faili la unit huifanya huduma iendelee kufanya kazi hata baada ya 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

Weka token nje ya unit. Iweke kwenye /etc/memmy/memory.env, inayomilikiwa na root, ikiwa na 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 katika matokeo ya status inamaanisha systemd haikuweza kuendesha ExecStart hata kidogo, kwa hivyo kagua which npm: ni /usr/bin/npm kwenye usakinishaji wa NodeSource na kitu fulani chini ya home directory ya mtumiaji kwenye nvm, ambayo systemd haitaipata. Unit inayoanza na kuzima mara moja imefeli ndani ya npm, na journalctl -u memmy-memory -n 50 huchapisha sababu. Mbinu hizi ni sawa na huduma nyingine yoyote ya systemd kwenye VPS.

Mambo ambayo Memmy haifanyi bado

• Hakuna toleo la Linux desktop. Hati za ufungashaji (packaging scripts) zinashughulikia macOS na Windows pekee, kwa hivyo workbench, wizard ya kuanza (onboarding wizard), na dashibodi ya kumbukumbu hazipatikani kwenye seva yenyewe.
• memory:serve:dev huendesha sehemu ya kuingilia ya TypeScript kupitia tsx, ambayo ni njia ya maendeleo (development path). Hifadhi hii pia inasambaza memory:serve kwa ajili ya matokeo yaliyokusanywa (compiled output). Endesha npm run bila hoja zozote ili kuona ni hati zipi ambazo checkout yako inazo kwa sasa.
• Urejeshaji (retrieval) hujenga dirisha lake la utafutaji kutoka kwa safu 2,000 za mwisho za vekta, kisha hutumia uteuzi wa Top-K ndani ya dirisha hilo. Kwenye hifadhi kubwa sana, kumbukumbu ya zamani inaweza kubaki nje ya dirisha hilo.
• Embedding hutokea baada ya kunasa data, na hitilafu ikitokea, kazi hupelekwa kwenye foleni ya kujaribu tena (retry queue) badala ya kuzuia zamu ya wakala. Kumbukumbu iliyoongezwa muda mfupi uliopita inaweza isiweze kupatikana kupitia utafutaji wa vekta bado.
• Faili moja ya SQLite inamaanisha nodi moja. Hakuna clustering, kwa hivyo seva ya pili ni kumbukumbu tofauti na ya pekee.

Toleo la 1.0.4 na takriban nyota 329 kufikia Julai 2026 linaelezea mradi ambao bado ni mchanga. Flags, paths, na majina ya hati hubadilika kati ya releases. Soma sehemu ya bin na matokeo ya npm run kwenye checkout yako mwenyewe badala ya kuamini amri iliyonakiliwa kutoka popote, ikiwemo hapa.

FAQ

Kwa nini ukaguzi wa afya (health check) unarejesha "connection refused"?

Hakuna kinachosikiliza kwenye port 18960. Msimbo wa kutoka wa curl 7 ukiwa na Failed to connect to 127.0.0.1 port 18960 inamaanisha huduma ya kumbukumbu (memory service) haifanyi kazi au ilikufa wakati wa kuanza, kwa hivyo soma terminal au journal ambapo ilianza. Sababu mbili za kawaida ni better-sqlite3 native module ambayo hailingani na toleo lako la Node, jambo linalorekebishwa kwa npm rebuild better-sqlite3, na toleo la Node lililo chini ya 22. Thibitisha socket kwa ss -lntp | grep 18960 mara tu huduma itakapokuwa juu.

Amri ya memmy-memory inatoka wapi baada ya kujenga (build) kutoka kwenye source?

Inatoka kwenye uwanja wa bin wa kifurushi cha workspace cha @memmy/memory, si kutoka kwa jina la repository. Tekeleza node -p "JSON.stringify(require('./Memory/package.json').bin)" ndani ya checkout na itachapisha {"memmy-memory":"./dist/src/cli/index.js"}. Faili hiyo ipo tu baada ya npm run memory:build, kwa sababu build hutengeneza dist na kuweka alama ya faili hiyo kuwa inaweza kutekelezeka (executable). Iendeshe kama node Memory/dist/src/cli/index.js health, au tengeneza symlink kwenye /usr/local/bin kwa ajili ya jina fupi.

Je, ninaweza kuongeza Memmy kwenye Claude Code kwa kutumia claude mcp add?

Hapana. Memmy ni MCP client, si MCP server. Inaunganisha nje kwenye seva zilizoorodheshwa chini ya tools.mcpServers katika ~/.memmy/config.yaml na kutoa zana zao kwa runtime yake yenyewe. Claude Code hufikia Memmy kwa njia nyingine, kwa kuendesha memmy-memory CLI kama amri ya shell, ikiongozwa na faili ya maelekezo ambayo memmy-memory init --agent huandika kwenye saraka ya sheria za wakala (agent's rules directory).

Je, kuendesha Memmy hutuma kumbukumbu zangu kwenye huduma ya wingu (cloud service)?

Uchanganuzi na uingizaji (ingestion) hufanyika ndani ya kifaa chako, na kumbukumbu huandikwa kwenye ~/.memmy/memory-service/memory.sqlite kwenye diski yako mwenyewe. MEMMY_CLOUD_SERVICE inaelekeza kwenye https://memmy-api.memtensor.cn kwa ajili ya hali ya akaunti na token za majaribio, na programu ya uboreshaji wa kumbukumbu inabaki imezimwa hadi utakapoiwasha. Njia ya kufuatilia ni mtoa huduma wa embedding: mfano wa embedding uliopangishwa (hosted) hupokea maandishi ya kila kumbukumbu inayogeuzwa kuwa vector, kwa hivyo tumia endpoint unayoiendesha mwenyewe ikiwa hilo ni muhimu kwako.