#1 Persistent memory for AI coding agents based on real-world benchmarks
Kodlama oturumları ve ajanlar arasında kalıcı bellek.
Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode ve her MCP istemcisi için kalıcı bellek.
🇬🇧 English • 🇨🇳 简体中文 • 🇹🇼 繁體中文 • 🇯🇵 日本語 • 🇰🇷 한국어 • 🇵🇹 Português • 🇧🇷 Português (Brasil) • 🇪🇸 Español • 🇩🇪 Deutsch • 🇫🇷 Français • 🇮🇹 Italiano • 🇳🇱 Nederlands • 🇵🇱 Polski • 🇨🇿 Čeština • 🇷🇴 Română • 🇭🇺 Magyar • 🇬🇷 Ελληνικά • 🇸🇪 Svenska • 🇩🇰 Dansk • 🇳🇴 Norsk • 🇫🇮 Suomi • 🇷🇺 Русский • 🇺🇦 Українська • 🇹🇷 Türkçe • 🇮🇱 עברית • 🇸🇦 العربية • 🇮🇳 हिन्दी • 🇧🇩 বাংলা • 🇵🇰 اردو • 🇹🇭 ไทย • 🇻🇳 Tiếng Việt • 🇮🇩 Bahasa Indonesia • 🇵🇭 Tagalog
Bu gist, Karpathy'nin LLM Wiki desenini güven puanlaması, yaşam döngüsü, bilgi grafları ve hibrit arama ile genişletir: agentmemory bunun uygulamasıdır.
Kurulum • Hızlı Başlangıç • Kıyaslamalar • Rakiplerle Karşılaştırma • Ajanlar • Nasıl Çalışır • MCP • Görüntüleyici • Yapılandırma • API
AgentMemory desteklenen oturum olaylarını kaydeder; kararları, düzeltmeleri ve dersleri farklı ajanlardan aranabilir hâle getirir. Görüntüleyicide anıları inceleyebilir, düzenleyebilir, dışa aktarabilir ve silebilirsiniz. Anahtar kelime araması API anahtarı gerektirmez; embedding’ler anlamsal arama ekler.
Kurulum
Gereksinimler:
- npm ve npx ile birlikte Node.js 20 veya daha yeni bir sürüm (
node -v,npm -vvenpx -v). - macOS/Linux otomatik ortam kurulumu için ayrıca
curl, POSIXshvetargerektirir. - Windows’ta WSL2 veya yerel Windows kurulumunu kullanın.
Standart, sıfırdan kurulum komutu:
npx -y @agentmemory/agentmemory@latest
Ajanları ve bir sağlayıcıyı ya da anahtarsız modu seçin. Kurulum yapılandırmayı kaydeder, bellek sunucusunu başlatır ve agentmemory komutunun genel kurulumunu sunar. -y npm istemini kabul eder; @latest güncel sürümü seçer. LLM sıkıştırması sağlayıcı ve AGENTMEMORY_AUTO_COMPRESS=true gerektirir.
Anahtarsız (keyless) mod, vektör embedding'lerini devre dışı bırakır. memory_recall (mem::search yolu) BM25 kullanır; memory_smart_search ise graf verisi zaten mevcutsa yapısal graf eşleşmelerini de füzyonlayabilir. Ücretsiz, cihaz üzerinde (on-device) semantik recall için ~/.agentmemory/.env içinde EMBEDDING_PROVIDER=local ayarlayın ve yeniden başlatın. İlk embedding isteği Xenova/all-MiniLM-L6-v2 modelini indirir; bu ilk model indirmesinden sonra çıkarım (inference) yerel olarak çalışır.
API http://localhost:3111, görüntüleyici http://localhost:3113 adresindedir. İkisi de varsayılan olarak yalnızca yerel bağlantıları dinler. Ayarlar ~/.agentmemory/.env dosyasındadır; bellek dizinleri ve ayrı örnekler için veri depolamaya bakın.
Ardından recall'ın çalıştığını kanıtlayın ve ajanınıza skill'lerini verin:
npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
Anahtar kelime aramaları, varsayılan anahtarsız modda BM25 üzerinden eşleşmelidir. Demo'nun database performance optimization sorgusu kasıtlı olarak semantiktir ve bir embedding sağlayıcısı yapılandırılana kadar sıfır sonuç döndürebilir.
Tüm işi bir kodlama ajanına bırakmayı mı tercih edersiniz? Ona şu tek talimatı verin:
Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
Başka bir ajanı agentmemory connect <agent> ile bağlayın. Entegrasyonlara ve günlük komutlara bakın.
Genel (global) kurulum / EACCES
npm install -g @agentmemory/agentmemory@latest
Yukarıdaki npx komutu, standart sıfırdan kurulum yolu olarak kalır ve global-prefix izin sorunlarından kaçınır.
npx eski bir sürüm sunuyor
npx, sürüm bazında önbelleğe alır. En güncel sürümü npx -y @agentmemory/agentmemory@latest ile zorlayın veya önbelleği bir kez rm -rf ~/.npm/_npx ile temizleyin (macOS/Linux; Windows'ta %LOCALAPPDATA%\npm-cache\_npx dizinini silin).
agentmemory, hook'ları, MCP'yi veya REST API'yi destekleyen her ajanla çalışır. Tüm ajanlar aynı bellek sunucusunu paylaşır.
|
Claude Code yerel eklenti + 12 hook + MCP |
Codex CLI yerel eklenti + 6 hook + MCP |
GitHub Copilot CLI MCP + eklenti hook'ları/skill'leri |
Cursor yerel eklenti + yaşam döngüsü hook’ları + MCP |
OpenCode yakalama eklentisi + MCP |
|
Devin 6 hook + skill + MCP |
OpenClaw yerel eklenti + MCP |
Hermes yerel eklenti + MCP |
pi yerel hatırlama + kayıt + beceriler |
OpenHuman yerel Memory trait backend'i |
|
Gemini CLI MCP sunucusu |
Antigravity MCP + hook'lar |
Claude Desktop MCP sunucusu |
Warp connect + MCP + skill'ler |
Zed MCP sunucusu |
|
Cline MCP sunucusu |
Continue MCP sunucusu |
Droid MCP sunucusu |
Kiro MCP sunucusu |
Qwen Code MCP sunucusu |
|
DeepSeek Harness yerel kayıt + MCP |
Roo Code MCP sunucusu |
Kilo Code MCP sunucusu |
Goose MCP sunucusu |
Aider REST API |
|
Oh My Pi yerel hatırlama + kayıt + beceriler + isteğe bağlı MCP |
||||
MCP veya HTTP konuşan her ajanla çalışır. Tek sunucu, hepsinde paylaşılan bellekler.
Veri depolama
Anılar varsayılan olarak deponun dışında tutulur:
| Platform | Veri dizini |
|---|---|
| macOS | ~/Library/Application Support/agentmemory |
| Linux | $XDG_DATA_HOME/agentmemory / ~/.local/share/agentmemory |
| Windows | %APPDATA%\agentmemory |
Örnek 0, mevcut ./data/state_store.db deposunu yeniden kullanır. --data-dir <path> veya AGENTMEMORY_DATA_DIR ile başka dizin seçin. Yeniden başlatma ve yükseltmelerde aynı dizini koruyun.
agentmemory --data-dir ~/.agentmemory-projects/main
agentmemory --instance 1
--instance 1, instance-1 alt dizinini, API için 3211 ve görüntüleyici için 3213 portunu kullanır. Redis ve taşıma için depolama ve yedekleme rehberine bakın.
En son sürüm notları: CHANGELOG.md.
Güncel bilgi getirme sonuçları, metrik tanımları ve yeniden üretme adımları:
0.9.31 · 2026-10-28 · strict recall-all@5 · eval/README.md.
Kaynaklarıyla birlikte ürünlerin ve dağıtım seçeneklerinin güncel karşılaştırması:
AgentMemory / Mem0 / Supermemory / Zep / Letta / Cognee / claude-mem · 2026-10-28.
30 saniyede deneyin
# Terminal 1: start the server
npx -y @agentmemory/agentmemory@latest
# Terminal 2: seed sample data and see recall in action
npx -y @agentmemory/agentmemory@latest demo
demo, 3 gerçekçi oturum (JWT auth, N+1 sorgu düzeltmesi, rate limiting) tohumlar (seed) ve bunlara karşı aramalar çalıştırır. Anahtarsız kurulumlar vektörleri devre dışı bırakır, bu yüzden mem::search anahtar kelime sorguları BM25 üzerinden eşleşmelidir; database performance optimization ise sıfır sonuç döndürebilir. smart-search, graf verisi mevcut olduğunda ek olarak yapısal graf eşleşmeleri döndürebilir. Semantik sorgunun N+1 düzeltmesini vektörler üzerinden bulmasını sağlamak için EMBEDDING_PROVIDER=local ayarlayın, yeniden başlatın ve ilk model indirmesinin tamamlanmasına izin verin.
Belleğin canlı olarak oluşumunu izlemek için http://localhost:3113 adresini açın.
Sıfırdan bir kurulumu doğrulayın ve yeniden başlatma kalıcılığını test edin
Sunucu çalışırken sağlığı, görüntüleyiciyi ve durumu kontrol edin:
curl -fsS http://localhost:3111/agentmemory/livez
curl -fsS http://localhost:3111/agentmemory/health
curl -fsS -o /dev/null http://localhost:3113/
npx -y @agentmemory/agentmemory@latest status
status sunucu sağlığını, sağlayıcıları, embedding modunu, kayıt teslimini ve kurtarmayı gösterir. Korumalı REST istekleri sunucu sırrını gerektirir. Ayarladıysanız kendi AGENTMEMORY_SECRET değerinizi kullanın; aksi hâlde üretilen yerel sırrı okuyun:
# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
-H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
-H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
Ardından npx -y @agentmemory/agentmemory@latest stop komutunu çalıştırın, Terminal 1'de standart komutu yeniden başlatın, /agentmemory/livez'i bekleyin ve aramayı tekrarlayın. Probe hâlâ döndürülmelidir. Özel bir --data-dir seçtiyseniz, yeniden başlatmada aynı dizini geçirin.
Günlük komutlar
Kurulum ve ayarlar yukarıdaki Kurulum bölümünde (ilk çalıştırma sizi adım adım yönlendirir). Günlük kullanımda:
agentmemory # start the server
agentmemory stop # stop it cleanly
agentmemory status
agentmemory capture
agentmemory capture --drain
agentmemory connect <agent> # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
Oturum Tekrar Oynatma (Session Replay)
agentmemory'nin kaydettiği her oturum tekrar oynatılabilir. Görüntüleyiciyi açın, Replay sekmesini seçin ve zaman çizelgesinde gezinin: prompt'lar, tool çağrıları, tool sonuçları ve yanıtlar; play/pause, hız kontrolü (0.5x - 4x) ve klavye kısayolları (açıp kapatmak için boşluk, adım adım ilerlemek için ok tuşları) ile ayrık olaylar olarak render edilir.
Daha eski Claude Code JSONL transkriptlerini içeri aktarmak için:
# Import everything under the default ~/.claude/projects
npx -y @agentmemory/agentmemory@latest import-jsonl
# Or import a single file
npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
İçe aktarılan oturumlar Replay’de yerel oturumların yanında görünür. Transkriptler indekslenir ve import kaynağıyla işaretlenir; işleme ayrıca oturum kristalleri ve dersler üretebilir.
import-jsonl'u birincil yakalama yolunuz olarak kullanıyorsanız dikkat: Claude Code'uncleanupPeriodDays'i (~/.claude/settings.jsoniçinde, varsayılan 30), bu pencereden daha eski JSONL transkriptlerini~/.claude/projects/dizininden otomatik olarak siler. agentmemory'yi aylar öncesine dayanan bir Claude Code geçmişine sıfırdan kurarsanız, 30 günden daha eski her şey ilk içe aktarmadan önce zaten silinmiş olur.import-jsonl'u bir cron üzerinde çalıştırın,cleanupPeriodDays'i daha yüksek bir değere çıkarın veya otomatik yakalama hook'larını bağlayın (varsayılan eklenti kurulum yolu) ki her turn, oturum canlıyken agentmemory'ye düşsün ve JSONL temizliği önemini kaybetsin.
Yükseltme / Bakım
Yerel runtime'ınızı kasıtlı olarak güncellemek istediğinizde bakım komutunu kullanın:
npx -y @agentmemory/agentmemory@latest upgrade
Komut yerel ortamı günceller ve geçerli çalışma alanındaki JavaScript bağımlılıklarını değiştirebilir. Verileri yedekleyin ve yükseltme rehberini okuyun.
Claude Code (tek blok, yapıştırın)
Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
Eklenti kurulumu olmadan Claude Code (MCP-bağımsız yol)
agentmemory'nin MCP sunucusunu /plugin install kullanmak yerine doğrudan ~/.claude.json üzerinden bağlarsanız, Claude Code ${CLAUDE_PLUGIN_ROOT}'u asla çözümlemez ve hook scriptlerini ~/.claude/settings.json içinde absolute path'lere yöneltmeniz gerekir. Bu path'ler genellikle agentmemory sürümünü gömer (örn. ~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…), bu yüzden bir sonraki yükseltme her hook'u sessizce bozar.
Geçici çözüm:
agentmemory connect claude-code --with-hooks
Bu, aynı hook komutlarını, şu anda kurulu olan @agentmemory/agentmemory paketinin paketlenmiş plugin/ dizinine çözümlenen absolute path'lerle ~/.claude/settings.json içine birleştirir. Path'leri yenilemek için agentmemory'yi yükselttikten sonra komutu yeniden çalıştırın. Aynı dosyadaki kullanıcı girdileri korunur; yalnızca önceki agentmemory girdileri değiştirilir. /plugin install yolunu kullanmak, önerilen yaklaşım olmayı sürdürür.
Uzak veya korumalı dağıtımlar için Claude Code'u AGENTMEMORY_URL ve AGENTMEMORY_SECRET ayarlanmış şekilde başlatın. Eklenti, her iki değeri de paketlenmiş MCP sunucusuna iletir; AGENTMEMORY_URL boş olduğunda MCP shim'i http://localhost:3111'i kullanır.
Codex CLI (Codex eklenti platformu)
# 1. start the memory server in a separate terminal
npx -y @agentmemory/agentmemory@latest
# 2. register the agentmemory marketplace and install the plugin
codex plugin marketplace add rohitg00/agentmemory
codex plugin add agentmemory@agentmemory
Codex eklentisi, Claude Code eklentisiyle aynı plugin/ dizininden gönderilir. Şunları kaydeder:
- Çalışan daemon'a giden, npm indirmesi veya fallback store gerektirmeyen paketlenmiş bir stdio MCP bridge. Yayınlanmamış bir build'i test etmek için yerel Codex kılavuzuna bakın.
- 6 yaşam döngüsü hook'u:
SessionStart,UserPromptSubmit,PreToolUse,PostToolUse,PreCompact,Stop - 9 çağrılabilir (invocable) skill:
/recall,/remember,/session-history,/forget,/recap,/handoff,/lesson,/commit-context,/commit-history, ve ajanın gerektiğinde yüklediği 8 referans skill (bellek disiplini, MCP tool'ları, REST API, yapılandırma, ajanlar, hook'lar, mimari ve skill yazma kılavuzu)
Codex'in hook engine'i, hook subprocess'lerine CLAUDE_PLUGIN_ROOT'u enjekte eder (codex-rs/hooks/src/engine/discovery.rs'a göre), bu yüzden aynı hook scriptleri her iki host'ta da kopyalama olmadan çalışır. Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure olayları yalnızca Claude Code'a özgüdür ve Codex için kaydedilmez.
Codex hook güveni ve uyumluluk
Native eklenti hook dispatch'i Codex CLI 0.150.1 ile doğrulanmıştır. Yakalama beklemeden önce eklenti hook'larına güvenin. Codex Desktop davranışı, paketlenmiş runtime'ına bağlıdır; bir geçici çözüm etkinleştirmeden önce /hooks'u kontrol edin ve yakalanan bir olayı doğrulayın.
Host'unuz global hook'lar gerektiriyorsa, komutları ~/.codex/hooks.json içine yansıtın. MCP zaten bağlıysa, mevcut connector'ın hook kurulumuna ulaşması için --force gerekir:
agentmemory connect codex --with-hooks --force
Bu, global hook'ları birleştirir ve agentmemory MCP girdisini yeniden yazarken ilgisiz girdileri korur. --force kullanmadan önce özel agentmemory endpoint ayarlarınızı gözden geçirin. Script path'lerini yenilemek için yükseltme sonrasında yeniden çalıştırın. Çift yakalamayı önlemek için native eklenti hook'larını veya global kopyaları etkinleştirin, ikisini birden değil.
GitHub Copilot CLI
VS Code agent modu için Copilot MCP ve otomatik yakalama kılavuzuna bakın. CLI connector'ı VS Code'u yapılandırmaz.
# MCP-only wiring
agentmemory connect copilot-cli
# Alternatif olarak, GitHub alt dizininden tam hook/skill eklentisi
copilot plugin install rohitg00/agentmemory:plugin
agentmemory connect copilot-cli, mcpServers.agentmemory'i ~/.copilot/mcp-config.json içine (veya COPILOT_HOME ayarlandığında $COPILOT_HOME/mcp-config.json içine) birleştirir ve mevcut sunucuları korur. Yerel Windows'ta bu, otomatikleştirilmiş tek connect adaptörüdür; diğer tüm yerel Windows ajanlarını manuel olarak yapılandırın. WSL connect, yalnızca hedef ajan aynı WSL ortamında kuruluysa desteklenir. Copilot, MCP sunucusunu bir sonraki başlatmada veya /mcp'den sonra alır. Tam hook/skill deneyimini istediğinizde eklentiyi de kurun.
Cursor
agentmemory connect cursor
Ardından Settings → Plugins → Add marketplace üzerinden .cursor-plugin/plugin.json içeren agentmemory dizinini seçin, agentmemory eklentisini etkinleştirin ve pencereyi yeniden yükleyin. Eklenti yaşam döngüsü kaydı, çalışma alanına göre proje ataması, beceriler ve MCP sağlar. Çift kaydı önlemek için eklenti hook’larını veya ~/.cursor/hooks.json içindeki elle eklenmiş hook’ları kullanın.
Pi, Oh My Pi, DeepSeek Harness
agentmemory connect pi --with-mcp
agentmemory connect omp --with-mcp
agentmemory connect dsh --with-hooks
Kullandığınız istemciye uygun komutu seçin. Pi ve OMP yerel hatırlama, kayıt, çevrimdışı yeniden gönderme ve beceriler kurar; --with-mcp tüm araçları ekler. Pi’de /reload çalıştırın veya OMP’yi yeniden başlatın, sonra /agentmemory-status ile kontrol edin. DSH, MCP’yi ve paketle gelen kayıt eklentisini kurar; bağlantıdan sonra DSH’yi yeniden başlatın.
Pi ayrıca kurulabilir @agentmemory/pi paketini destekler. Yerel kurulum ve npm durumu için Pi rehberine bakın. Her istemcide tek kurulum yöntemi kullanın.
OpenClaw (bu prompt'u yapıştırın)
Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
{
"mcpServers": {
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"],
"env": {
"AGENTMEMORY_URL": "http://localhost:3111"
}
}
}
}
Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
Tam kılavuz: integrations/openclaw/
Hermes Agent (bu prompt'u yapıştırın)
Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
mcp_servers:
agentmemory:
command: npx
args: ["-y", "@agentmemory/mcp"]
memory:
provider: agentmemory
Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
Tam kılavuz: integrations/hermes/
Diğer ajanlar
Bellek sunucusunu başlatın: npx -y @agentmemory/agentmemory@latest
npx skills add ile yerel skill'ler
agentmemory, Claude-Code-tarzı <dir>/SKILL.md formatında 17 skill sunar: 9 çağrılabilir aksiyon skill'i (remember, recall, recap, handoff, forget, lesson, commit-context, commit-history, session-history) ve ajanın gerektiğinde yüklediği 8 referans skill (memory-discipline, agentmemory-mcp-tools, agentmemory-rest-api, agentmemory-config, agentmemory-agents, agentmemory-hooks, agentmemory-architecture, write-agentmemory-skill). Referans skill'ler, kaynaktan üretilen veri tablolarını taşır, bu yüzden asla sapmazlar. vercel-labs'ın skills CLI'si, bunları çağıran ajanın yerel skill dizinine 50+ ajanda (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf ve daha fazlası) otomatik olarak kurar:
npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
npx skills add rohitg00/agentmemory -y -a warp # explicit agent
npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
Bu, agentmemory connect <agent>'ı tamamlayıcı niteliktedir:
agentmemory connect <agent>genellikle MCP yapılandırmasını yazar. Hermes, OpenClaw, Pi ve Oh My Pi varsayılan olarak yerel entegrasyonu ve becerileri kurar; MCP için--with-mcpkullanılır.npx skills add rohitg00/agentmemory, yerel becerileri paketlenmemiş ajanlara beceri kurar. Hermes, OpenClaw, Pi ve Oh My Pi için bu adımı atlayın; bağlayıcıları becerileri zaten kurar.
skills CLI'sinin henüz kapsamadığı birkaç ajan için (Zed v1.3.x ve altı), 17 SKILL.md dosyasını ajanın yerel skill dizinine kendiniz bırakın; aynı format her yerde çalışır.
Standart MCP bloğu
agentmemory girdisi, mcpServers şeklini kullanan her host'ta (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw) aynı MCP sunucu bloğudur:
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"],
"env": {
"AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
"AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
}
}
Bu girdiyi, host'un yapılandırma dosyasındaki mevcut mcpServers nesnesine birleştirin; dosyayı değiştirmeyin (replace). Dosyada zaten başka sunucular varsa, agentmemory'yi mcpServers içine başka bir key olarak onların yanına ekleyin. mcpServers tamamen eksikse, bloğu { "mcpServers": { ... } } içine yapıştırın. ${VAR} placeholder'ları, MCP-sunucu başlatıldığında AGENTMEMORY_URL / AGENTMEMORY_SECRET'ı shell'den devralır; ayarlanmamış değişkenler boş string geçirir ve shim, http://localhost:3111'e düşer. Bağlanmış tek bir girdi, hem yerel hem de uzak (k8s / reverse-proxied) dağıtımları kapsar.
| Ajan | Yapılandırma dosyası | Notlar |
|---|---|---|
| Cursor (yalnızca MCP) | ~/.cursor/mcp.json |
mcpServers'a birleştirin veya agentmemory connect cursor. Web sitesinde tek tıkla deeplink de mevcuttur. |
| Cursor (tam eklenti) | .cursor-plugin/ |
Eklenti Cursor IDE ve cursor-agent için yaşam döngüsü hook’ları, çalışma alanı tespiti, beceriler ve MCP sağlar. Cursor kurulumuna bakın. |
| Claude Desktop | claude_desktop_config.json (Application Support) |
mcpServers'a birleştirin. Düzenledikten sonra Claude Desktop'ı yeniden başlatın. |
| Cline / Roo Code / Kilo Code | Cline MCP ayarları (Settings UI → MCP Servers → Edit) | Aynı mcpServers bloğu. |
| Devin CLI (MCP + hook'lar) | ~/.config/devin/config.json |
agentmemory connect devin, MCP girdisini birleştirir; --with-hooks, Devin'in küçük harfli tool matcher'larıyla altı yerel otomatik yakalama hook'u (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) ekler. devin mcp list ile ve devin içinde /hooks ile doğrulayın. |
| Devin CLI (tam eklenti) | plugin/.devin-plugin/ |
Bir checkout'tan devin plugins install ./plugin, 17 skill'in tümünü /agentmemory:<skill> slash komutları olarak ve MCP sunucusunu kaydeder. Devin eklenti hook'ları SessionStart/SessionEnd'i tetikleyemez, bu yüzden tam oturum yakalaması için bunu connect devin --with-hooks ile eşleştirin. |
| Devin (cloud) | Settings → Connections → MCP servers | Özel bir MCP (STDIO) ekleyin: komut npx, args -y @agentmemory/mcp@latest, env olarak ağ üzerinden erişilebilir bir agentmemory dağıtımına işaret eden AGENTMEMORY_URL ve AGENTMEMORY_SECRET (cloud oturumları localhost'a erişemez — bkz. ../deploy/). Secret'ı Devin Secrets içinde saklayın, ardından 54 tool'un tümünün göründüğünü doğrulamak için "Test listing tools"u kullanın. |
| Gemini CLI | ~/.gemini/settings.json |
gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user (otomatik birleştirir). |
| GitHub Copilot CLI (yalnızca MCP) | ~/.copilot/mcp-config.json |
agentmemory connect copilot-cli, mcpServers.agentmemory'i birleştirir; Copilot bunu bir sonraki başlatmada veya /mcp'den sonra alır. |
| GitHub Copilot CLI (tam eklenti) | Copilot eklenti kurulumu | GitHub alt dizininden eklenti için copilot plugin install rohitg00/agentmemory:plugin. |
| OpenClaw | OpenClaw MCP yapılandırması | Aynı mcpServers bloğu. Daha derin entegrasyon: openclaw plugins install ./integrations/openclaw, OpenClaw'ın bellek slot'unu talep eder (memory-core'dan otomatik geçer); plugins.entries.agentmemory.hooks.allowConversationAccess=true ayarlayın, aksi halde turn yakalama sessizce bloklanır. Bkz. integrations/openclaw. |
| Codex CLI (yalnızca MCP) | .codex/config.toml |
TOML şekli: codex mcp add agentmemory -- npx -y @agentmemory/mcp, veya manuel olarak [mcp_servers.agentmemory] ekleyin. |
| Codex CLI (tam eklenti) | Codex eklenti marketplace'i | codex plugin marketplace add rohitg00/agentmemory, ardından codex plugin add agentmemory@agentmemory. MCP + 6 yaşam döngüsü hook'u + 17 skill kaydeder. Host'unuzda hook'lara güvenin ve yakalamayı doğrulayın; bkz. Codex kurulumu ve doğrulaması. |
| OpenCode (yalnızca MCP) | opencode.json |
Farklı bir şekil: üst seviye mcp key'i, dizi olarak komut: {"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}. |
| OpenCode (tam eklenti) | plugin/opencode/ |
Oturum yaşam döngüsünü, mesajları, tool'ları, hataları kapsayan 22 otomatik yakalama hook'u. Proje attribution'ı oturum başınadır, bu yüzden birden fazla repository'ye yayılan tek bir OpenCode süreci, her oturumu kendi projesi altında dosyalar. İki slash komutu (/recall, /remember). plugin/opencode/'u OpenCode workspace'inize kopyalayın ve eklenti girdisini opencode.json'a ekleyin. Tam hook tablosu + boşluk analizi için plugin/opencode/README.md'a bakın. |
| pi | ~/.pi/agent/extensions/agentmemory |
agentmemory connect pi --with-mcp. yerel hatırlama + kayıt + beceriler. /reload, /agentmemory-status. Pi. |
| Oh My Pi | ~/.omp/agent |
agentmemory connect omp --with-mcp. yerel hatırlama + kayıt + beceriler. Oh My Pi. |
| Hermes Agent | ~/.hermes/config.yaml |
cp -r integrations/hermes ~/.hermes/plugins/agentmemory + memory.provider: agentmemory, 6-hook'lu bellek sağlayıcısını verir (prefetch, turn yakalama, oturum sonu, pre-compress, MEMORY.md mirroring, sistem prompt bloğu). hermes plugins doctor ve hermes memory status ile doğrulayın. Bkz. integrations/hermes. |
| Qwen Code | ~/.qwen/settings.json |
agentmemory connect qwen, standart mcpServers bloğunu yazar. Hook payload'u Claude Code ile alan uyumludur (field-compatible), bu yüzden mevcut 12-hook'lu scriptler değişiklik yapılmadan çalışır; bunları aynı settings.json içindeki hooks bölümü üzerinden bağlayın. |
| Antigravity IDE / 2.0 | ~/.gemini/config/mcp_config.json |
agentmemory connect antigravity --with-hooks, paylaşılan customization dizinine MCP ve yakalama hook'larını kurar. Bkz. Antigravity kurulumu ve sınırları. |
Antigravity CLI (agy) |
~/.gemini/config/mcp_config.json |
agentmemory connect antigravity-cli --with-hooks, güncel IDE sürümleriyle aynı MCP ve hook yapılandırmasını kullanır. Mevcut kurulumlar --force ile yenilenmelidir; bkz. yükseltme notları. |
| Kiro | ~/.kiro/settings/mcp.json |
agentmemory connect kiro, kullanıcı seviyesindeki yapılandırmayı yazar. Workspace geçersiz kılmaları, kodunuzun yanındaki .kiro/settings/mcp.json içine gider. |
| Warp | ~/.warp/.mcp.json |
agentmemory connect warp, standart mcpServers bloğunu yazar. Warp, ayrıca .claude/skills/'ten skill'leri otomatik keşfeder; Claude Code eklentisi kurulduğunda 9 agentmemory skill'i (remember, recall, recap, handoff, forget, lesson, commit-context, commit-history, session-history), Warp'ın slash-komut paletinde yerli olarak görünür. |
| Cline (CLI) | ~/.cline/data/settings/cline_mcp_settings.json |
agentmemory connect cline, standart mcpServers bloğunu yazar. VS Code eklenti kullanıcıları: aynı bloğu Cline Settings → MCP Servers → Edit JSON üzerinden yapıştırın. |
| Continue.dev | ~/.continue/config.yaml (tercih edilen) veya config.json (eski/legacy) |
agentmemory connect continue, yapılandırma yoksa config.yaml oluşturur veya mevcut config.json dosyasını değiştirir. Mevcut YAML için yorumları ve çapaları koruyarak mcpServers: altına eklenecek bloğu gösterir. Continue nesne yerine dizi kullanır. |
| Zed | ~/.config/zed/settings.json |
agentmemory connect zed, context_servers altına yazar (Zed'in key'i, mcpServers DEĞİL). Uzak MCP sunucuları, bunun yerine {"url": "..."} üzerinden bağlanabilir. |
| Droid (Factory.ai) | ~/.factory/mcp.json |
agentmemory connect droid, standart mcpServers bloğunu yazar. Proje kapsamlı geçersiz kılmalar <repo>/.factory/mcp.json içine gider. Yerel otomatik yakalama için --with-hooks geçirin. |
| DeepSeek Harness | $DSH_HOME/cordis.patch.yml |
agentmemory connect dsh MCP araçlarını etkinleştirir. AgentMemory ile gelen yerel kayıt eklentisini yüklemek için --with-hooks ekleyin. Ayrı bir eklenti paketi gerekmez. DSH. |
| Goose | Goose MCP ayarları arayüzü | Aynı mcpServers bloğu; goose configure → Add Extension → MCP kullanın. ~/.config/goose/config.yaml'da doğrudan YAML düzenleme desteklenir, ancak şema extensions: + cmd kullanır (mcpServers: + command değil). |
| Aider | yok | Betiklerden kaydetmek ve aramak için kimlik doğrulamalı REST örneklerini kullanın. |
| Desteklenen ajanlar | Yalnızca beceriler | npx skills add rohitg00/agentmemory; yüklenecek becerileri ve hedef ajanları seçin. |
Host'un localhost'una erişemeyen sandboxlanmış MCP istemcileri (Flatpak / Snap / kısıtlayıcı container'lar) için: env bloğunda ayrıca "AGENTMEMORY_FORCE_PROXY": "1" ayarlayın ve AGENTMEMORY_URL'i sandbox'ın gerçekten erişebileceği bir rotaya (örn. LAN IP'niz) işaret edin.
Programatik erişim (Python / Rust / Node)
Herhangi bir dilden REST API’yi, bir ajandan MCP araçlarını kullanın. REST, JSON ve bearer kimlik doğrulaması kullanır; kayıt ve arama örneğine bakın. Doğrudan ortam entegrasyonu için Python örneklerini inceleyin.
Kaynaktan
git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start
npm start, kurulu CLI ile aynı yerel sunucuyu başlatır. Gereksinimler Kurulum bölümündedir; API ve görüntüleyici 127.0.0.1 üzerinde dinler.
Windows
agentmemory Windows 10/11’de çalışır. WSL2 Linux yolunu izleyerek engine’i otomatik kurabilir. Yerel Windows’ta iii-engine v0.25.0 elle kurulmalıdır: arşivi iii v0.25.0 sürüm sayfasından indirin, checksum’u doğrulayın ve iii.exe dosyasını PATH üzerine koyun. CLI Windows ZIP’ini otomatik açmaz
Yerel Windows’ta otomatik MCP yapılandırması yalnızca agentmemory connect copilot-cli için vardır; diğerleri için Other agents bölümünü kullanın. WSL’de connect yalnızca hedef agent aynı WSL ortamındaysa çalıştırılmalıdır
Yalnızca standalone MCP (engine olmadan). REST API, görüntüleyici veya runtime hizmetleri gerekmiyorsa:
npx -y @agentmemory/agentmemory@latest mcp
# or
npx -y @agentmemory/mcp
agentmemory doctor çalıştırın veya --verbose ile yeniden başlatın. Portlar doluysa --port <N> veya --instance <N> kullanın. Uyumluluk ve kurtarma için yükseltme rehberine bakın.
Deploy
Kendi sunucunuz için Docker Compose veya aşağıdaki şablonları kullanın. Bellek ve kimlik bilgileri /data birimindedir; yükseltirken yedekleyin ve yeniden kullanın. Kimlik doğrulama, ağ, yedekler ve taşıma için dağıtım rehberine bakın.
Render'ın tek tıkla deploy butonu, repository root'unda bir render.yaml gerektirir; bunu kasıtlı olarak temiz tutuyoruz. Repo içindeki blueprint'e manuel olarak işaret etmek için ../deploy/render/ içinde belgelenen Render Blueprint akışını kullanın.
Tam kurulum detayları (HMAC yakalama, görüntüleyici SSH tüneli, rotasyon, yedekleme,
maliyet tabanları) ../deploy/ içinde yaşar:
../deploy/fly:auto_stop_machines = "stop"ile tek makine; en ucuz boşta kalma (idle).../deploy/railway: Hobby plan sabit ücret, dashboard'da volume.../deploy/render: Blueprint akışı, ücretli planlarda otomatik disk snapshot'ları.../deploy/coolify: Coolify ile kendi VPS'inizde self-hosted; aynı Docker Compose stack'i, host'a ve veriye siz sahip olursunuz.
REST 3111, görüntüleyici 3113 portunu kullanır. Özel ağda tutun veya kimlik doğrulama ve TLS ile koruyun. Platform ayarları ve eski Docker kurulumu taşıması dağıtım rehberindedir.
Proje bilgisi sohbetlere ve talimat dosyalarına dağılır. AgentMemory önceki kararları, düzeltmeleri ve dersleri kullandığınız ajandan aranabilir hâle getirir.
Yerleşik ajan belleğiyle karşılaştırma
Her AI kodlama ajanı, yerleşik bellekle gelir: Claude Code'da MEMORY.md, Cursor'da notepad'ler, Cline'da memory bank vardır. Bunlar yapışkan not (sticky note) gibi çalışır. agentmemory, yapışkan notların arkasındaki aranabilir veritabanıdır.
| Yerleşik (CLAUDE.md) | agentmemory | |
|---|---|---|
| Bakım | Elle düzenlenen talimatlar | İndekslenmiş oturum geçmişi ve anılar |
| Arama | Her şeyi bağlama yükler | BM25 + vektör + graf (yalnızca top-K) |
| Ajanlar arası | Ajan başına dosyalar | MCP + REST (herhangi bir ajan) |
| Koordinasyon | Yok | Lease'ler, signal'ler, action'lar, routine'ler |
| Gözlemlenebilirlik | Dosyaları manuel okuma | :3113'te gerçek zamanlı görüntüleyici |
Bellek Pipeline'ı
PostToolUse hook fires
-> Stable event ID / durable capture inbox / offline spool
-> Privacy filter (strip secrets, API keys)
-> Store raw observation
-> Synthetic compression by default
(LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
-> Vector embedding when an embedding provider is active
-> Index in BM25, plus vectors when enabled
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
-> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
-> Inject context when enabled by the integration
4 Katmanlı Bellek Konsolidasyonu
İnsan beyninin belleği nasıl işlediğine (uyku konsolidasyonu dahil) göre modellenmiştir.
| Katman | Ne | Analoji |
|---|---|---|
| Working (Çalışma) | Tool kullanımından ham gözlemler | Kısa süreli bellek |
| Episodic (Olaysal) | Sıkıştırılmış oturum özetleri | "Ne oldu" |
| Semantic (Anlamsal) | Çıkarılan gerçekler ve desenler | "Ne bildiğim" |
| Procedural (Yöntemsel) | İş akışları ve karar desenleri | "Nasıl yapılır" |
Bellekler zamanla çürür (Ebbinghaus eğrisi). Sık erişilen bellekler güçlenir. Bayatlamış (stale) bellekler otomatik olarak tahliye edilir (auto-evict). Çelişkiler tespit edilir ve çözülür.
Ne Yakalanır
Tablo Claude Code hook’larını açıklar. Diğer entegrasyonlar istemcilerinin sunduğu olayları kaydeder. Ortak hook’lar üzerinden otomatik bağlam ekleme isteğe bağlıdır: AGENTMEMORY_INJECT_CONTEXT=true.
| Hook | Yakaladığı |
|---|---|
SessionStart |
Proje path'i, oturum ID'si |
UserPromptSubmit |
Kullanıcı prompt'ları (privacy-filtrelenmiş) |
PreToolUse |
Dosya erişim desenleri + zenginleştirilmiş bağlam |
PostToolUse |
Tool adı, girdi, çıktı |
PostToolUseFailure |
Hata bağlamı |
PreCompact |
Compaction öncesi belleği yeniden enjekte eder |
SubagentStart/Stop |
Sub-agent yaşam döngüsü |
Stop |
Oturum sonu özeti |
SessionEnd |
Oturum tamamlandı işareti |
Temel Yetenekler
| Yetenek | Açıklama |
|---|---|
| Otomatik yakalama | Yerel entegrasyonların kaydettiği desteklenen oturum ve araç olayları |
| Semantik arama | RRF füzyonuyla BM25 + vektör + bilgi grafı |
| Bellek evrimi | Versiyonlama, supersession, ilişki grafları |
| Recall hijyeni | Supersede edilmiş bellek sürümleri arama indekslerinden çıkar; KV'deki sürüm zinciri tam geçmişi korur |
| Yakın-tekrar ipuçları | Yeni içerik mevcut bir belleğe yakından benzediğinde kayıtlar bilgilendirici bir similarTo eşleşmesi bildirir |
| Ajan başına scope'lama | agentId, REST, MCP ve arama indeksi genelinde paylaşılan veya izole modda kaydetme ve recall boyunca iş görür |
| Yazma anı kökeni (provenance) | Her gözlem ve bellek, yakalama, kaydetme ve içe aktarma anında damgalanan değiştirilemez bir köken kanalı taşır (user, agent, tool, import veya shared) |
| Otomatik unutma | TTL süresinin dolması, çelişki tespiti, önem bazlı tahliye |
| Önce gizlilik | API anahtarları, secret'lar, <private> etiketleri depolamadan önce temizlenir |
| Kendi kendini onarma | Circuit breaker, sağlayıcı fallback zinciri, health monitoring |
| Claude köprüsü | MEMORY.md ile iki yönlü senkronizasyon |
| Bilgi grafı | Entity çıkarımı + BFS traversal |
| Takım belleği | Takım üyeleri arasında namespace'lenmiş paylaşılan + özel bellek |
| Alıntı kökeni | Herhangi bir belleği kaynak gözlemlere kadar izleyin |
| Git snapshot'ları | Bellek durumunu versiyonlayın, geri alın (rollback) ve diff'leyin |
Üç sinyali birleştiren üçlü-stream retrieval:
| Stream | Ne yapar | Ne zaman |
|---|---|---|
| BM25 | Eş anlamlı genişletmeli stem'lenmiş anahtar kelime eşleştirme | Her zaman açık |
| Vektör | Dense embedding'ler üzerinde kosinüs benzerliği | Embedding sağlayıcısı yapılandırıldığında |
| Graf | Entity eşleştirme üzerinden bilgi grafı traversal'ı | Sorguda entity tespit edildiğinde |
Reciprocal Rank Fusion (RRF, k=60) ile füzyonlanır ve oturum bazında çeşitlendirilir (oturum başına en fazla 3 sonuç).
Bir vektör indeksi doldurulduğunda, mem::search (memory_recall'un arkasında) hybrid BM25 + vektör ranker'ı kullanır. Embedding olmadan BM25 kullanır. smart-search, anahtarsız modda dahi graf verisi mevcut olduğunda ek olarak yapısal graf eşleşmelerini füzyonlayabilir. Lesson recall'u, her sorguda tüm corpus'u taramak yerine özel bir bellek içi (in-memory) BM25 indeksinde çalışır. Supersede edilmiş bellek sürümleri her recall yolundan hariç tutulur; sürüm zinciri geçmişlerini korur.
0.9.31: AGENTMEMORY_VECTOR_BACKFILL=all / AGENTMEMORY_VECTOR_BACKFILL_MAX.
BM25, Yunanca, Kiril, İbranice, Arapça ve aksanlı Latin'i kutudan çıktığı gibi tokenize eder. Çince / Japonca / Korece bellekler için, CJK run'larını kelime seviyesinde token'lara bölmek üzere opsiyonel segmenter'ları kurun (npm install @node-rs/jieba tiny-segmenter); bunlar olmadan agentmemory, tüm-run tokenizasyonuna yumuşak geçiş yapar (soft-falls) ve stderr'de tek seferlik bir ipucu yazdırır.
Embedding sağlayıcıları
Anahtarsız kurulumlar vektör embedding'lerini devre dışı bırakır: mem::search, BM25 kullanır; smart-search ise ek olarak mevcut yapısal graf verisini de kullanabilir. Ücretsiz, cihaz üzerinde semantik embedding'lere opt-in yapmak için şunu ~/.agentmemory/.env'e ekleyin ve agentmemory'yi yeniden başlatın:
EMBEDDING_PROVIDER=local
Normal npm kurulumu, opsiyonel @huggingface/transformers runtime'ını içerir. İlk embedding isteği Xenova/all-MiniLM-L6-v2'yi indirir, bu yüzden ağ erişimine ihtiyaç duyar ve daha uzun sürebilir; sonraki çıkarımlar (inference) cihaz üzerinde çalışır. Uzak sağlayıcılar, EMBEDDING_PROVIDER onları geçersiz kılmadığı sürece kendi anahtarlarından otomatik olarak algılanır.
| Sağlayıcı | Model | Maliyet | Notlar |
|---|---|---|---|
| Yerel (önerilen opt-in) | all-MiniLM-L6-v2 |
Ücretsiz | EMBEDDING_PROVIDER=local |
| Gemini | gemini-embedding-001 |
Ücretsiz katman | 100+ dil, 768/1536/3072 boyut (MRL), 2048-token girdi. text-embedding-004'ün yerini alır (kullanımdan kaldırıldı, 14 Oca 2026'da durduruldu) |
| OpenAI | text-embedding-3-small |
OpenAI | text-embedding-3-small |
| Voyage AI | voyage-code-3 |
Ücretli | Kod için optimize edilmiş |
| Cohere | embed-english-v3.0 |
Ücretsiz deneme | Genel amaçlı |
| OpenRouter | Herhangi bir model | Değişken | Çoklu-model proxy |
54 tool, 6 kaynak, 3 prompt ve 17 skill.
MCP shim vs tam sunucu: yayımlanan
@agentmemory/mcppaketi ince bir shim'dir. Tam 54-tool yüzeyini yalnızcaAGENTMEMORY_URLüzerinden çalışan bir agentmemory sunucusuna erişebildiğinde (proxy modu) açığa çıkarır. Erişilebilir sunucu olmadığında, shim yerel bir 7-tool kümesine düşer (memory_save,memory_recall,memory_smart_search,memory_sessions,memory_export,memory_audit,memory_governance_delete).AGENTMEMORY_TOOLS=core|allenv değişkeni, sunucu tarafı bir flag'dir; bunu shim'inenvbloğunda ayarlamak hiçbir etki yapmaz. Cursor / OpenCode / Gemini CLI'de yalnızca 7 tool görüyorsanız,npx -y @agentmemory/agentmemory@latest'i (veya Docker stack'ini) başlatın veAGENTMEMORY_URL=http://localhost:3111'i ayarlayın.
54 Tool
Küçükten büyüğe üç tool yüzeyi: AGENTMEMORY_TOOLS=core, görünürlüğü 8 temel tool'a indirir (memory_save, memory_recall, memory_consolidate, memory_smart_search, memory_sessions, memory_diagnose, memory_lesson_save, memory_reflect); aşağıdaki temel (base) küme, registry'nin 14 temel (foundational) tool'udur; varsayılan (AGENTMEMORY_TOOLS=all), 54'ünün tamamını açığa çıkarır.
Temel tool'lar (14)
| Tool | Açıklama |
|---|---|
memory_recall |
Geçmiş gözlemleri arar |
memory_compress_file |
Markdown dosyalarını yapıyı koruyarak sıkıştırır |
memory_save |
Bir içgörüyü, kararı veya deseni kaydeder |
memory_file_history |
Belirli dosyalarla ilgili geçmiş gözlemler |
memory_patterns |
Tekrarlayan desenleri tespit eder |
memory_sessions |
Son oturumları listeler |
memory_smart_search |
Hybrid semantik + anahtar kelime arama |
memory_vision_search |
Görüntü gözlemlerini arar |
memory_timeline |
Kronolojik gözlemler |
memory_profile |
Proje profili (concept'ler, dosyalar, desenler) |
memory_export |
Tüm bellek verisini dışa aktarır |
memory_relations |
İlişki grafını sorgular |
memory_commit_lookup |
Bir git commit'inin arkasındaki oturumlar |
memory_commits |
Bir oturum için kaydedilen commit'ler |
Genişletilmiş tool'lar (toplam 54, varsayılan yüzey)
| Tool | Açıklama |
|---|---|
memory_patterns |
Tekrarlayan desenleri tespit eder |
memory_timeline |
Kronolojik gözlemler |
memory_relations |
İlişki grafını sorgular |
memory_graph_query |
Bilgi grafı traversal'ı |
memory_consolidate |
4 katmanlı konsolidasyonu çalıştırır |
memory_claude_bridge_sync |
MEMORY.md ile senkronize eder |
memory_team_share |
Takım üyeleriyle paylaşır |
memory_team_feed |
Son paylaşılan öğeler |
memory_audit |
İşlemlerin audit izi |
memory_governance_delete |
Audit izi ile siler |
memory_snapshot_create |
Git-versiyonlu snapshot |
memory_action_create |
Bağımlılıklarla iş öğeleri oluşturur |
memory_action_update |
Action durumunu günceller |
memory_frontier |
Önceliğe göre sıralanmış bloklanmamış action'lar |
memory_next |
En önemli tek bir sonraki action |
memory_lease |
Özel action lease'leri (çoklu ajan) |
memory_routine_run |
İş akışı routine'lerini örnekler (instantiate) |
memory_signal_send |
Ajanlar arası mesajlaşma |
memory_signal_read |
Receipt'lerle mesajları okur |
memory_checkpoint |
Harici koşul kapıları (gates) |
memory_mesh_sync |
Instance'lar arasında P2P senkronizasyon |
memory_sentinel_create |
Olay güdümlü (event-driven) izleyiciler |
memory_sentinel_trigger |
Sentinel'leri harici olarak tetikler |
memory_sketch_create |
Geçici (ephemeral) action grafları |
memory_sketch_promote |
Kalıcıya yükseltir (promote) |
memory_crystallize |
Action zincirlerini sıkıştırır |
memory_diagnose |
Sağlık kontrolleri |
memory_heal |
Takılı durumu otomatik düzeltir |
memory_facet_tag |
Boyut:değer etiketleri |
memory_facet_query |
Facet etiketlerine göre sorgular |
memory_verify |
Kökeni (provenance) izler |
6 Kaynak · 3 Prompt · 17 Skill
| Tür | Ad | Açıklama |
|---|---|---|
| Kaynak | agentmemory://status |
Health, oturum sayısı, bellek sayısı |
| Kaynak | agentmemory://project/{name}/profile |
Proje başına intelligence |
| Kaynak | agentmemory://project/{name}/recent |
Bir proje için son gözlemler |
| Kaynak | agentmemory://memories/latest |
Son 10 aktif bellek |
| Kaynak | agentmemory://graph/stats |
Bilgi grafı istatistikleri |
| Kaynak | agentmemory://team/{id}/profile |
Paylaşılan takım profili |
| Prompt | recall_context |
Arar + bağlam mesajları döndürür |
| Prompt | session_handoff |
Ajanlar arasında veri handoff'u |
| Prompt | detect_patterns |
Tekrarlayan desenleri analiz eder |
| Skill | /recall |
Belleği arar |
| Skill | /remember |
Uzun süreli belleğe kaydeder |
| Skill | /session-history |
Son oturum özetleri |
| Skill | /forget |
Gözlemleri/oturumları siler |
Tablo, dört temel skill'i gösterir. Tam küme, 9 çağrılabilir skill ve 8 referans skill'den oluşur; yukarıdaki Native skill'ler bölümüne bakın.
Bağımsız MCP
Tam sunucu olmadan, herhangi bir MCP istemcisi için çalıştırın. Bunlardan herhangi biri işe yarar:
npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
npx -y @agentmemory/mcp # shim package alias
Veya ajanınızın MCP yapılandırmasına ekleyin:
Çoğu ajan (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
{
"mcpServers": {
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"],
"env": {
"AGENTMEMORY_URL": "http://localhost:3111"
}
}
}
}
agentmemory girdisini, dosyayı değiştirmek yerine host'unuzun mevcut mcpServers nesnesine birleştirin. Host'un localhost'una erişemeyen sandboxlanmış istemciler için, env bloğuna "AGENTMEMORY_FORCE_PROXY": "1" ekleyin ve AGENTMEMORY_URL'i sandbox'ın erişebileceği bir rotaya ayarlayın.
OpenCode (opencode.json):
{
"mcp": {
"agentmemory": {
"type": "local",
"command": ["npx", "-y", "@agentmemory/mcp"],
"enabled": true
}
},
"plugin": ["./plugins/agentmemory-capture.ts"]
}
Eklenti dosyasını repo'dan kopyalayın:
mkdir -p ~/.config/opencode/plugins
cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
3113 portunda otomatik başlar. Görüntüleyici, bağlandığında bir snapshot yükler (GET /agentmemory/viewer/snapshot) ve ardından canlı stream olaylarını uygular: yeni bellekler, dersler, gözlemler, audit girdileri, graf değişiklikleri ve health güncellemeleri polling veya sayfa yenileme olmadan görünür. Diğer tek istekler, tıkladığınız action'lar, "load more" sayfaları ve aramalardır. Stream düştüğünde, görüntüleyici rakamlarının ne kadar eski olduğunu gösterir, backoff ile yeniden bağlanır ve bir snapshot'tan yeniden senkronize olur.
- Canlı sayımlarla, deep link'lerle (
#memories/<id>,#sessions/<id>?obs=<id>,#graph/<id>,#health/consolidation), klavye kısayollarıyla ve bir mobil menüyle dört grupta 12 sekme. - Memories: server-side arama, proje, ajan ve türe göre filtreler, sürüm zinciri ve bir kelime diff'i olan bir detay paneli, provenance link'leri, id, MCP çağrısı ve bir curl komutu için kopyalama butonları, düzenleme (yeni bir sürüm), onayla forget, toplu (bulk) forget ve JSON export.
- Sessions: okunabilir tool girdisi ve çıktısıyla satır içi (inline) bir gözlem zaman çizelgesi, filtreler ve sayfalama, ve her oturumun ürettiği bellekler ve dersler.
- Graph: arama, ilişkiler ve kaynaklarla düğüm (node) detayı, yalnızca renge dayanmayan bir legend ve zoom kontrolleri.
- Health:
GET /agentmemory/status'un canlı versiyonu. Her problem, çözümüyle birlikte gelir; ayrıca state backend'i, indeks kayıt durumu, graf provenance compaction ilerlemesi ve gerçek eşiklerle bir konsolidasyon açıklayıcısı. - Audit, Activity, Profile, Replay, Lessons, Actions ve Crystals sayfaları; her biri bölümün ne olduğunu, neden boş olduğunu ve onu doldurabilecek komutu söyleyen bir boş durum (empty state) ile ve her terim ve sayı üzerinde bir
?sözlük tooltip'i ile.
open http://localhost:3113
Görüntüleyici sunucusu, varsayılan olarak 127.0.0.1'e bağlanır ve istekleri REST API'ye ilettiğinde sunucu secret'ını ekler, bu yüzden hiçbir kuruluma gerek yoktur. REST ile servis edilen /agentmemory/viewer endpoint'i, normal bearer-token kurallarını izler ve token'ı olmayan tarayıcıları görüntüleyici portuna yönlendirir. CSP header'ları, yanıt başına bir script nonce'ı kullanır ve satır içi (inline) handler özniteliklerini devre dışı bırakır (script-src-attr 'none').
LLM Sağlayıcıları
agentmemory, sağlayıcıları ortamınızdan otomatik olarak algılar. Bir sağlayıcı, LLM destekli işlemleri kullanılabilir kılar; ancak yalnızca sağlayıcı yapılandırması, LLM tarafından yazılan gözlem sıkıştırmasını etkinleştirmez. Bu yol, hem bir sağlayıcıyı hem de AGENTMEMORY_AUTO_COMPRESS=true'yu gerektirir.
| Sağlayıcı | Config | Notlar |
|---|---|---|
| No-op (varsayılan) | Config gerekmez | LLM destekli compress/summarize devre dışı. Synthetic sıkıştırma ve BM25 recall hâlâ çalışır. Claude-subscription fallback'e güveniyorduysanız aşağıdaki AGENTMEMORY_ALLOW_AGENT_SDK'ya bakın. |
| Anthropic API | ANTHROPIC_API_KEY |
Token başına faturalandırma |
| MiniMax | MINIMAX_API_KEY |
Anthropic uyumlu |
| Gemini | GEMINI_API_KEY |
Embedding'leri de etkinleştirir |
| OpenRouter | OPENROUTER_API_KEY |
Herhangi bir model |
| OpenAI API | OPENAI_API_KEY |
Varsayılan gpt-5.6-luna, OPENAI_MODEL ile geçersiz kılın |
| Yerel (Ollama / LM Studio / vLLM / llama.cpp) | OPENAI_API_KEY=local + OPENAI_BASE_URL=http://localhost:11434/v1 (Ollama) veya http://localhost:1234/v1 (LM Studio) + OPENAI_MODEL=<your model> |
OpenAI-API-uyumlu her şey. Sıfır maliyet, kendi hardware'inizde çalışır. Aşağıdaki Yerel modeller bölümüne bakın. |
| Claude subscription fallback | AGENTMEMORY_ALLOW_AGENT_SDK=true |
Yalnızca opt-in. @anthropic-ai/claude-agent-sdk oturumlarını spawn eder; eskiden sınırsız Stop-hook recursion'ına neden oluyordu, bu yüzden artık varsayılan değildir. |
Yerel modeller (Ollama / LM Studio / vLLM)
agentmemory, OpenAI-API-uyumlu herhangi bir sunucuyla konuşur, bu yüzden /v1/chat/completions'ı expose eden her şey kod değişikliği yapılmadan çalışır. Ücretli anahtar yok, cloud yok, rate limit yok; tamamen kendi hardware'inizde çalışır.
Ollama (varsayılan port 11434):
ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
ollama serve
# ~/.agentmemory/.env
OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=qwen3:8b
LM Studio (varsayılan port 1234):
LM Studio'yu açın → Local Server sekmesi → Start Server. Picker'dan herhangi bir chat modeli seçin (Qwen 3, gpt-oss, DeepSeek R1, vb.).
# ~/.agentmemory/.env
OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
OPENAI_BASE_URL=http://localhost:1234/v1
OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
vLLM / llama.cpp / Text Generation Inference: aynı şekil. OPENAI_BASE_URL'i sunucunuzun expose ettiği URL'e işaret edin ve OPENAI_MODEL'i sunucunuzun kabul edeceği bir isme ayarlayın.
Bellek işleri için model seçimleri: sıkıştırma ve özetleme, bir 7B instruct modelin yeterli olduğu kısa görevlerdir (<2K token girdi, <500 token çıktı). Öneriler:
| Model | Boyut | Neden |
|---|---|---|
qwen3:8b |
~5.2 GB | 16 GB'lık bir makinede dengeli varsayılan; çıkarımda ve tool-şekilli metinde güçlü |
qwen3:4b |
~2.6 GB | En küçük makul seçenek; sıkıştırma için iyi, graf çıkarımı için daha zayıf |
qwen3-coder:30b |
~19 GB | 24-32 GB hardware'de kod-şekilli oturumlar için en iyi yerel seçim (30B MoE, 3.3B aktif) |
gpt-oss:20b |
~14 GB | 16 GB RAM'e sığan güçlü genel model |
deepseek-r1:8b |
~5.2 GB | Reasoning distill; daha yavaş ama daha temiz çıkarımlar |
Qwen 3 modelleri varsayılan olarak "düşünür" (think) ve herhangi bir çıktıdan önce tüm token bütçesini reasoning'de yakabilir. Graf-çıkarım prompt'larına /no_think eklemek için AGENTMEMORY_LLM_NOTHINK=1 ayarlayın ve çıkarımlar boş gelirse MAX_TOKENS'ı yükseltin (16384 işe yarar).
Reasoning sınıfı modeller (<think> bloklarıyla o1 tarzı), yerel sunucunuzun açığa çıkarmayabileceği bir reasoning field'ı ile boş content döndürebilir. Çıkarımlar boş gelirse, önce reasoning-olmayan bir modele geçin. OPENAI_REASONING_EFFORT=none env'i, OpenAI reasoning şemasını yansıtan Ollama Cloud thinking modellerinde de thinking'i devre dışı bırakabilir.
Yerel embedding'ler opsiyonel bir bağımlılık olarak gelir, ancak varsayılan olarak etkin değildir. Xenova/all-MiniLM-L6-v2'ye (384-dim) opt-in yapmak için EMBEDDING_PROVIDER=local ayarlayın. İlk embedding isteği modeli indirir; sonrasında çıkarım cihaz üzerinde yapılır. Bu ayar veya uzak bir embedding anahtarı olmadan, vektörler devre dışı kalır, mem::search BM25 kullanır ve smart-search hâlâ mevcut graf eşleşmelerini ekleyebilir.
Maliyet bilincine sahip model seçimi
Kayıt ve anahtar kelime araması için anahtarsız başlayın. EMBEDDING_PROVIDER=local, model indirildikten sonra yerel anlamsal arama sağlar. LLM sıkıştırması sağlayıcı ve AGENTMEMORY_AUTO_COMPRESS=true gerektirir; her gözlem bir istek oluşturabileceğinden güncel fiyatları kontrol edin. Görüntüleyici ve agentmemory status etkin sağlayıcıları gösterir.
Çoklu-ajan belleği (AGENT_ID + AGENTMEMORY_AGENT_SCOPE)
Birden fazla rolün tek bir agentmemory sunucusunu paylaştığı çoklu-ajan kurulumlarında (architect / developer / reviewer / researcher / support-agent), AGENT_ID her yazmayı onu yapan rol ile etiketler. AGENTMEMORY_AGENT_SCOPE, recall'ın bu etikete göre filtreleyip filtrelemeyeceğini kontrol eder.
TEAM_ID=company
USER_ID=engineering-team
AGENT_ID=architect
AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
İki mod:
| Mod | Yazmaları etiketler | Recall'ı filtreler | Ne zaman kullanılır |
|---|---|---|---|
shared (varsayılan) |
evet | hayır | Audit izi ile ajanlar arası bağlam. Architect, developer'ın not ettiğini görebilir, ancak her satır kimin söylediğini kaydeder. |
isolated |
evet | evet | Katı ayrım. Architect, developer'ın gözlemlerini / belleklerini / oturumlarını asla görmez. |
AGENT_ID ayarlandığında ne etiketlenir: Session.agentId, RawObservation.agentId, CompressedObservation.agentId, Memory.agentId. Rol, api::session::start → mem::observe → mem::compress → KV şeklinde akar.
İzole modda ne filtrelenir: mem::smart-search, /agentmemory/memories, /agentmemory/observations, /agentmemory/sessions. Her endpoint, istek başına geçersiz kılmak için ?agentId=<role> ve env scope'undan tamamen opt-out etmek için ?agentId=* kabul eder. /memories ayrıca, agentId'si undefined olan AGENT_ID-öncesi bellekleri yüzeye çıkarmak için ?includeOrphans=true kabul eder.
SDK / REST katmanında çağrı başına geçersiz kılma: her mutasyon endpoint'i (/session/start, /remember), env'in önüne geçen bir agentId field'ını istek gövdesinde kabul eder. Birçok rolü tek bir sunucu sürecinden yönlendiren runtime'lar için kullanışlıdır. MCP memory_save tool'u aynı agentId field'ını açığa çıkarır, bağımsız stdio sunucusu hem agentId'yi hem project'i iletir ve kaydedilen bellekler agentId'yi arama indeksine taşır, bu yüzden ajan-scope'lu arama, gözlemlerin yanı sıra bellekleri de kapsar.
AGENT_ID ayarlanmadığında, bellek scope'suz kalır (eski/legacy davranış, etiket yok, filtre yok).
Portlar
| Port | Amaç | Ortam değişkeni |
|---|---|---|
3111 |
REST API, MCP HTTP ve canlı görüntüleyici olayları | III_REST_PORT |
3113 |
Görüntüleyici arayüzü | III_VIEWER_PORT |
--port <N> REST portunu ve varsayılan görüntüleyici portunu N+2 olarak ayarlar. --instance N ayrı ortam oluşturur. İç portlar özel kalmalıdır; uzaktan erişimden önce dağıtım rehberini okuyun.
Depolama: dosya veya Redis
Varsayılan dosya deposu ayrı veritabanı gerektirmez. Redis, AGENTMEMORY_STATE_BACKEND=redis ve AGENTMEMORY_REDIS_URL ile isteğe bağlıdır. Backend değişikliği mevcut belleği taşımaz. Kalıcılık, Redis sınırları ve kimlik doğrulamalı dışa/içe aktarım depolama rehberindedir.
Yapılandırma Dosyası
Runtime yapılandırmasını her shell’de değişken export etmek yerine ~/.agentmemory/.env içine koyun.
İşlem ortam değişkenleri dosyadaki değerlerden önce gelir. Yapılandırma değişince sunucuyu yeniden başlatın.
%USERPROFILE%\.agentmemory\.env
New-Item -ItemType Directory -Force $HOME\.agentmemory
notepad $HOME\.agentmemory\.env
Bir API anahtarı yerine bir Claude Code Pro/Max subscription'ı ile test etmek için, açıkça opt-in yapın:
AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true
LLM tarafından yazılan gözlem sıkıştırması her iki satırı gerektirir: bir LLM sağlayıcısına erişim (bu açık subscription fallback'i dahil) ve AGENTMEMORY_AUTO_COMPRESS=true. Yalnızca bir sağlayıcı, varsayılan synthetic sıkıştırma yolunu yerinde bırakır.
Konsolidasyon (graf düğümleri, dersler, crystal'lar), bir LLM sağlayıcısı yapılandırıldığında varsayılan olarak açıktır. LLM'siz çalışma istiyorsanız CONSOLIDATION_ENABLED=false ile açıkça opt-out yapın. Graf çıkarımı ayrı bir flag'dir:
GRAPH_EXTRACTION_ENABLED=true
# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
Ortam Değişkenleri
~/.agentmemory/.env için yaygın seçenekler. Bağlam ekleme ve sıkıştırma isteğe bağlıdır; sıkıştırma ayrıca sağlayıcı gerektirir. core modu görünür MCP araçlarını sınırlar:
EMBEDDING_PROVIDER=local
# AGENTMEMORY_INJECT_CONTEXT=true
# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
# AUTO_FORGET_ENABLED=false
# LESSON_DECAY_ENABLED=false
# INSIGHT_DECAY_ENABLED=false
Tam .env.example sağlayıcıları, kayıt filtrelerini, saklama sürelerini, depolamayı, ekipleri ve isteğe bağlı özellikleri kapsar. AGENTMEMORY_ENV_FILE başka dosya seçer. Doldurulmuş .env veya bearer sırrını asla commit etmeyin.
3111 portunda 146 endpoint. REST API, varsayılan olarak 127.0.0.1'e bağlanır. Korumalı endpoint'ler Authorization: Bearer <secret> gerektirir ve mesh sync endpoint'leri her iki peer'da da açıkça ayarlanmış bir AGENTMEMORY_SECRET gerektirir.
Kimlik doğrulama varsayılan olarak açıktır. AGENTMEMORY_SECRET ayarlanmamışsa CLI ilk başlatmada ~/.agentmemory/secret dosyasında 0600 izinleriyle rastgele bir sır oluşturur ve seçilen veri dizinine de kopyalar. Paketli istemciler yerel sunucuya bağlanırken buradan okur; secret yalnız loopback URL’lerine (localhost, 127.0.0.0/8, ::1) gönderilir. Uzak istemciler secret’ı kendi ortamında sağlamalıdır. Docker self-host ve deploy/ kendi secret’larını üretir. API’yi elle çağırmak için:
curl -H "Authorization: Bearer <secret-from-data-dir>" http://localhost:3111/agentmemory/health
Yazmalar için istek kuralları. REST API'ye ve görüntüleyiciye yapılan POST, PUT, PATCH ve DELETE istekleri, bir body taşıdıklarında Content-Type: application/json göndermelidir (bir charset parametresi sorun değildir) ve mevcutsa bir Origin header'ı, yapılandırılmış REST veya görüntüleyici portu için bir loopback origin'i olmalı veya VIEWER_ALLOWED_ORIGINS içinde listelenmiş olmalıdır (virgülle ayrılmış, örn. https://memory.example.com). Origin header'ı göndermeyen istemciler (CLI, hook'lar, MCP, curl, server-to-server) etkilenmez. Görüntüleyici de kendi origin'ini kabul eder.
Dosya path'leri. Dosya okuyan veya yazan endpoint'ler (/compress-file, /replay/import-jsonl, /graph/import-graphify), yalnızca ~/.agentmemory, instance veri dizini veya AGENTMEMORY_IMPORT_ROOT içinde listelenen bir dizin altındaki path'leri kabul eder (birden fazlasını : ile, Windows'ta ; ile ayırın). /replay/import-jsonl, ayrıca varsayılan ~/.claude/projects'i de kabul eder. /obsidian/export, AGENTMEMORY_EXPORT_ROOT içinde ve /migrate, ~/.agentmemory içinde kalır. Symlink'ler her kontrolden önce çözümlenir.
Secret temizliği (scrubbing). API anahtarları, bearer token'lar, PEM private key blokları ve URL'lere gömülü credential'lar (scheme://user:password@host), metin saklanmadan önce her yazma yolunda redakte edilir: gözlemler, remember, evolve, slot'lar, dersler, action'lar, sketch'ler, signal'ler, checkpoint'ler, import'lar, jsonl replay, mesh sync, takım paylaşımları, sıkıştırma ve özet çıktısı, crystal'lar ve graf düğümleri.
Temel endpoint'ler
| Method | Path | Açıklama |
|---|---|---|
GET |
/agentmemory/health |
Health check (her zaman public) |
GET |
/agentmemory/status |
Neyin yanlış olduğu ve nasıl düzeltileceği (tarayıcılar için HTML, aksi halde JSON) |
GET |
/agentmemory/viewer/snapshot |
Görüntüleyicinin gösterdiği her şey, tek bir yanıtta |
POST |
/agentmemory/session/start |
Oturumu başlat + bağlamı al |
POST |
/agentmemory/session/end |
Oturumu sonlandır |
POST |
/agentmemory/observe |
Gözlemi yakala (aşağıdaki yakalama teslimatına bakın) |
GET |
/agentmemory/capture |
Yakalama inbox'ı, dead letter'lar ve offline spool |
POST |
/agentmemory/capture/retry |
Dead-letter yakalamalarını yeniden dene |
POST |
/agentmemory/capture/drain |
Yerel offline spool'u şimdi gönder |
POST |
/agentmemory/smart-search |
Hybrid arama |
POST |
/agentmemory/context |
Bağlam üret |
POST |
/agentmemory/remember |
Uzun süreli belleğe kaydet |
POST |
/agentmemory/forget |
Gözlemleri sil |
POST |
/agentmemory/enrich |
Dosya bağlamı + bellekler + bug'lar |
GET |
/agentmemory/profile |
Proje profili |
GET |
/agentmemory/export |
Tüm veriyi dışa aktar |
POST |
/agentmemory/import |
JSON'dan içe aktar |
POST |
/agentmemory/graph/query |
Bilgi grafı sorgusu |
POST |
/agentmemory/graph/compact |
Aşırı büyümüş graf provenance'ını kırp |
POST |
/agentmemory/team/share |
Takımla paylaş |
GET |
/agentmemory/audit |
Audit izi |
Tam endpoint listesi: Üretilen REST referansı
Yakalama teslimatı. Hook'lar, her gözlemi bir eventId ile POST /agentmemory/observe'a bir kez gönderir. Bu, payload'un bir id'si olduğunda (örneğin Claude Code'un tool_use_id'si) çağrı için host'un kendi id'sidir, aksi halde oturumun, hook türünün, tool adının, girdinin, çıktının ve host timestamp'inin bir hash'idir. Sunucu, olayı state store'daki bir yakalama inbox'ına yazar, gözlemi saklar, ardından inbox girdisini kaldırır. Durum kodu ne olduğunu söyler:
| Durum | status field'ı |
Anlamı |
|---|---|---|
201 |
accepted |
Saklandı. observationId, yeni gözlemdir. |
202 |
accepted (state: "retrying") |
Kabul edildi, ancak saklama başarısız oldu. Sunucu, yeniden başlatmadan sonra da onu yeniden dener. |
200 |
duplicate |
Bu eventId zaten kabul edilmişti. observationId, mevcut gözlemdir; yeni bir şey saklanmaz. |
400 / 422 |
rejected |
Geçersiz payload, veya saklama kalıcı olarak başarısız oldu (olay bir dead letter olarak tutulur). |
503 |
rejected (retryable: true) |
Inbox dolu (AGENTMEMORY_CAPTURE_INBOX_MAX). Hook'lar olayı spool'lar ve daha sonra gönderir. |
Başarısız olaylar, AGENTMEMORY_CAPTURE_MAX_ATTEMPTS'e (5) kadar, ikiye katlanan backoff ile her AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS'de (10 sn) yeniden denenir. Hâlâ başarısız olan olaylar, dead letter olarak inbox'ta kalır, /agentmemory/status ve görüntüleyicinin Health sayfasında listelenir ve POST /agentmemory/capture/retry ile ({"eventId": "..."} veya {"all": true}) yeniden denenebilir. Kabul edilen olay id'leri, AGENTMEMORY_CAPTURE_DEDUP_HOURS (168 saat, en fazla AGENTMEMORY_CAPTURE_EVENTS_MAX id) boyunca hatırlanır, bu yüzden bir timeout veya yeniden başlatma sonrası yeniden oynatılan bir hook bir kez saklanır; oysa kendi host id'lerine sahip iki ayrı tool çağrısı, içerikleri identik olsa bile iki kez saklanır. Bir gözlem silindiğinde (forget, oturum silme, eviction, otomatik unutma veya depoyu değiştiren bir import), olayı, gözlem kaldırılmadan önce silinmiş olarak işaretlenir, bu yüzden aynı pencere içinde o olayın yeniden oynatılması bir duplicate olarak yanıtlanır ve hiçbir şey saklamaz. State store, diske her 2 saniyede bir yazar, bu yüzden yanıtlanan bir olay hâlâ bir an için yalnızca bellekte olabilir. Bunu kapsamak için, her 2xx yanıtı ayrıca sunucunun bootId'sini (her başlatmada yeni), acceptedAt'ını ve durableAfterMs'ini (kalıcılığın operatörün ayarı olduğu dosya deposunda kayıt aralığı artı 1.5 sn, redis'te 1.5 sn) taşır. Hook'lar, o pencere geçene kadar olayı yerel spool'da tutar ve başka bir istek göndermeden daha sonraki bir çağrıda onu siler. O zamana kadar bootId değiştiyse, sunucu yeniden başlamıştır, bu yüzden hook, olayı aynı eventId ile yeniden gönderir; diske ulaşmış bir olay iki kez saklanmaz. Sunucu, ayrıca başlangıçta ve her retry aralığında bu tür olayları kendisi de gönderir, bu yüzden bir yeniden başlatma, daha sonra hiçbir hook çalışmasa da hiçbir şey kaybetmez. Daha eski hook'lar ekstra field'ları yok sayar ve daha eski bir sunucuya karşı yeni hook'lar, olayı eskisi gibi 2xx'te atar.
Sunucu kapalıyken, zamanında yanıt vermediğinde veya bir 5xx döndürdüğünde, hook gözlemi yerel bir spool dosyasına ekler, <data dir>/capture-spool/<host>-<port>.jsonl (klasörü AGENTMEMORY_CAPTURE_SPOOL_DIR ile geçersiz kılın). Dosya, kullanıcınıza özeldir (mod 600), secret'lar sunucunun onları redakte ettiği şekilde redakte edilir, en fazla AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES (5 MiB) tutar ve AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS'tan (168) daha eski girdileri düşürür. Dolduğunda, yeni girdiler düşürülür ve sayılır ve /agentmemory/status bunu bildirir. Hook, hâlâ zaman limiti içinde 0 ile çıkar ve sunucu sağlıklı olduğunda hiçbir istek eklemez. Spool, bir sonraki başlatmada ve sunucuya yeniden ulaşan ilk hook tarafından, ajan beklemesin diye bir arka plan sürecinde gönderilir. Event id'leri bunu güvenli kılar: bir timeout'tan önce ulaşan bir gözlem iki kez saklanmaz. npx @agentmemory/agentmemory capture, spool'u ve sunucu inbox'ını gösterir, --drain spool'u şimdi gönderir ve GET /agentmemory/capture, aynısını JSON olarak döndürür. Spool'u kapatmak için AGENTMEMORY_CAPTURE_SPOOL=false ayarlayın.
Graf provenance'ını kırpma (compacting). Eski provenance verilerinin kırpılması, eski scope’ların tamamını okuduğu için başlangıçta ertelenir. /agentmemory/status, deferred veya AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false olduğunda off bildirir. Aşağıdaki manuel kırpmayı bakım sırasında çalıştırın. Arama indeksi geçişi ayrıdır: bakım kılavuzunda açıklandığı gibi agentmemory graph-index migrate --allow-legacy-scan kullanın.
Elle çalıştırmak için, POST /agentmemory/graph/compact'ı çağırın. Her düğümü ve kenarı listelemek yerine ad ve kenar-key indekslerinde yürür ve yeniden çalıştırmak güvenlidir. Id'leri kırptığında bir graph_compact audit girdisi yazar.
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{}'
Büyük bir depoda veya çağrı 504 döndürdüğünde, bunu parçalar halinde çalıştırın. scope (nodes, edges veya history), offset ve limit gönderin, ardından null olana kadar döndürülen nextOffset ile yeniden çağırın. Bunu nodes, edges ve history için yapın ve bir {"scope":"snapshot"} çağrısıyla bitirin, çünkü parçalı bir çalıştırma önbelleğe alınmış snapshot'a dokunmaz.
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
npm run dev # Hot reload
npm run build # Production build
npm test # 4,000+ tests
npm run test:integration # API tests (requires running services)
Gereksinimler Kurulum bölümündedir. Katkı kuralları ve sürüm kontrolleri CONTRIBUTING.md dosyasındadır.