Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

86.7 KB
Raw Blame

agentmemory: AI kodlama ajanları için kalıcı bellek

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

rohitg00/agentmemory | Trendshift

Design doc: 1.6k stars / 230 forks on the gist

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.

npm version CI License Stars skills.sh installs

54 MCP tools 12 auto hooks 0 external DBs 4,000+ tests passing

agentmemory demo

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 -v ve npx -v).
  • macOS/Linux otomatik ortam kurulumu için ayrıca curl, POSIX sh ve tar gerektirir.
  • 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).


Works with every agent

agentmemory, hook'ları, MCP'yi veya REST API'yi destekleyen her ajanla çalışır. Tüm ajanlar aynı bellek sunucusunu paylaşır.

Claude Code
Claude Code
yerel eklenti + 12 hook + MCP
Codex CLI
Codex CLI
yerel eklenti + 6 hook + MCP
GitHub Copilot CLI
GitHub Copilot CLI
MCP + eklenti hook'ları/skill'leri
Cursor
Cursor
yerel eklenti + yaşam döngüsü hook’ları + MCP
OpenCode
OpenCode
yakalama eklentisi + MCP
Devin
Devin
6 hook + skill + MCP
OpenClaw
OpenClaw
yerel eklenti + MCP
Hermes
Hermes
yerel eklenti + MCP
pi
pi
yerel hatırlama + kayıt + beceriler
OpenHuman
OpenHuman
yerel Memory trait backend'i
Gemini CLI
Gemini CLI
MCP sunucusu
Antigravity
Antigravity
MCP + hook'lar
Claude Desktop
Claude Desktop
MCP sunucusu
Warp
Warp
connect + MCP + skill'ler
Zed
Zed
MCP sunucusu
Cline
Cline
MCP sunucusu
Continue
Continue
MCP sunucusu
Droid
Droid
MCP sunucusu
Kiro
Kiro
MCP sunucusu
Qwen Code
Qwen Code
MCP sunucusu
DeepSeek Harness
DeepSeek Harness
yerel kayıt + MCP
Roo Code
Roo Code
MCP sunucusu
Kilo Code
Kilo Code
MCP sunucusu
Goose
Goose
MCP sunucusu
Aider
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.


Benchmarks

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.


vs Competitors

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.


Quick Start

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'un cleanupPeriodDays'i (~/.claude/settings.json iç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.

Cursor

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.

Pi · Oh My Pi · DSH

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-mcp kullanı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.

Deploy to fly.io Deploy to Railway

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.


Why agentmemory

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

How It Works

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

MCP Server

54 tool, 6 kaynak, 3 prompt ve 17 skill.

MCP shim vs tam sunucu: yayımlanan @agentmemory/mcp paketi ince bir shim'dir. Tam 54-tool yüzeyini yalnızca AGENTMEMORY_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|all env değişkeni, sunucu tarafı bir flag'dir; bunu shim'in env bloğ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 ve AGENTMEMORY_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/

Real-Time Viewer

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').


Configuration

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.


API

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"}'

Development

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.

License

Apache-2.0