Kodlama ajanınız her şeyi hatırlar. Artık yeniden açıklamaya gerek yok.
iii engine üzerine inşa edilmiştir
Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode ve her MCP istemcisi için kalıcı bellek.
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
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 üzerinde otomatik iii-engine kurulumu ayrıca `curl`, bir POSIX `sh` ve `tar` gerektirir. `node:20-slim` gibi minimal imajlar bunları içermeyebilir.
- Yerel (native) Windows, sabitlenmiş iii-engine v0.22.1 `iii.exe` dosyasının manuel olarak kurulmasını gerektirir. WSL2 veya Docker Desktop, desteklenen diğer yollardır.
Standart, sıfırdan kurulum komutu:
```bash
npx -y @agentmemory/agentmemory@latest
```
İlk çalıştırma, etkileşimli bir kurulumdur: bağlanacak ajanları seçersiniz (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), bir LLM sağlayıcısı seçersiniz veya anahtarsız (keyless) kalırsınız; kurulum yapılandırmayı oluşturur, bellek sunucusunu ve sabitlenmiş iii engine'ini başlatır ve tek başına `agentmemory` komutunun her yerde çalışması için genel (global) olarak kurulmasını önerir. `-y`, npx'in paket istemini kabul eder ve `@latest`, eski bir önbelleğe alınmış sürümden kaçınır. Bir sağlayıcı, LLM özelliklerini kullanılabilir kılar; ancak LLM tarafından yazılan gözlem sıkıştırması yalnızca `AGENTMEMORY_AUTO_COMPRESS=true` da ayarlandığında başlar.
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.
Yerel runtime dört port kullanır: REST/MCP HTTP için `3111`, iii stream'leri için `3112`, görüntüleyici için `3113` ve iii worker WebSocket'i için `49134`. Kalıcı iii state'i macOS'ta `~/Library/Application Support/agentmemory`, Linux'ta `$XDG_DATA_HOME/agentmemory` veya `~/.local/share/agentmemory`, Windows'ta ise `%APPDATA%\agentmemory` içinde yaşar. Bunu geçersiz kılmak için `--data-dir ` veya `AGENTMEMORY_DATA_DIR` kullanın ve her yeniden başlatmada aynı değeri yeniden kullanın. Geriye dönük uyumluluk için, mevcut bir `./data/state_store.db` veya `./data/iii-config.yaml`, instance 0 için platform varsayılanına göre önceliklidir; açık bir flag veya ortam değişkeni geçersiz kılma yine de kazanır.
Ardından recall'ın çalıştığını kanıtlayın ve ajanınıza skill'lerini verin:
```bash
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
`agentmemory connect ` ile her zaman daha fazla ajan bağlayabilirsiniz — [Her ajanla çalışır](#works-with-every-agent) bölümünde listelenen 20 adaptör. Tam komut referansı [Hızlı Başlangıç](#quick-start) bölümünde.
Windows
Hızlı yol WSL2'dir. Yerel Windows engine kurulumu, sabitlenmiş v0.22.1 ZIP dosyasının indirilmesini ve `iii.exe`'nin manuel olarak çıkarılmasını gerektirir; CLI bunu otomatik olarak çıkarmaz. Docker Desktop de desteklenir. Adım adım anlatım için [Windows notları](#windows) bölümüne bakın.
Genel (global) kurulum / EACCES
```bash
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).
Kendi iii engine'inizi zaten çalıştırıyorsanız
agentmemory, iii-engine v0.22.1'i sabitler ve farklı bir sürüme bağlanmaz (worker, başka bir engine'in protokolünü konuşamaz). Diğer engine'i durdurun, ardından `npx -y @agentmemory/agentmemory@latest` komutunu çalıştırın. Bu, sabitlenmiş v0.22.1'i `~/.agentmemory/bin` içine kurar ve çalıştırır; kendi `iii`'nizi dokunulmamış bırakır.
---
agentmemory, hook'ları, MCP'yi veya REST API'yi destekleyen her ajanla çalışır. Tüm ajanlar aynı bellek sunucusunu paylaşır.
MCP veya HTTP konuşan her ajanla çalışır. Tek sunucu, hepsinde paylaşılan bellekler.
---
Her oturumda aynı mimariyi yeniden açıklarsınız. Aynı bug'ları yeniden keşfedersiniz. Aynı tercihleri yeniden öğretirsiniz. Yerleşik bellek (CLAUDE.md, .cursorrules) 200 satırda tıkanır ve eskir. agentmemory bunu düzeltir. Ajanınızın yaptıklarını sessizce yakalar, aranabilir belleğe sıkıştırır ve bir sonraki oturum başladığında doğru bağlamı enjekte eder. Tek komut. Ajanlar arasında çalışır.
**Ne değişir:** 1. oturumda JWT auth kurdunuz. 2. oturumda rate limiting istiyorsunuz. Ajan, auth'unuzun `src/middleware/auth.ts` içinde jose middleware kullandığını, testlerinizin token doğrulamasını kapsadığını ve Edge uyumluluğu için jsonwebtoken yerine jose'yi seçtiğinizi zaten bilir; yeniden açıklama ve kopyala-yapıştır yapmadan.
```bash
npx -y @agentmemory/agentmemory@latest
```
Varsayılan olarak agentmemory, iii-engine state'ini onu başlattığınız repodan ayrı bir yerde saklar: macOS'ta `~/Library/Application Support/agentmemory`, Linux'ta `$XDG_DATA_HOME/agentmemory` veya `~/.local/share/agentmemory`, Windows'ta ise `%APPDATA%\agentmemory`. Mevcut bir eski (legacy) `./data/state_store.db` veya `./data/iii-config.yaml`, bu platform varsayılanından önce instance 0 için yeniden kullanılır. Bir konumu açıkça seçmek için `--data-dir ` geçirin veya `AGENTMEMORY_DATA_DIR` ayarlayın; her iki açık ayar da eski (legacy) keşfe göre önceliklidir:
```bash
npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
```
Native ve Docker başlatmaları, aynı çözümlenmiş host dizinini kullanır; Docker bunu `/data` üzerine bind-mount eder. `--instance 1`, çözümlenmiş dizine `instance-1` ekler ve ayrı varsayılan port dörtlüsünü `3211/3212/3213/49234` seçer.
En son sürüm notları: [CHANGELOG.md](../CHANGELOG.md).
---
### Geri Getirme Doğruluğu
**coding-agent-life-v1** (şirket içi (in-house) corpus, sandbox'ta yeniden üretilebilir)
| Adaptör | P@5 | R@5 | İlk 5'te bulma oranı | p50 gecikme |
|---|---|---|---|---|
| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
| grep baseline | 0.227 | 0.967 | 15 / 15 | 0 ms |
Bu corpus için **P@5 matematiksel tavanında** (0.240, scorecard'a bakın) %100 ilk-5 bulma oranı. Hybrid, her gold oturumu getirir; grep, çok-oturumlu temporal sorguda 2 gold'dan 1'ini kaçırır. Kazanım **recall + temporal**'dir, toplam precision değil. Bu benchmark küçüktür ve gold açısından seyrektir; aşağıdaki daha büyük LongMemEval-S daha iyi ayrıştırır. Tam tür bazlı döküm + düzeltme notu: [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md).
**LongMemEval-S** (ICLR 2025, 500 soru)
| Sistem | R@5 | R@10 | MRR |
|---|---|---|---|
| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
| Yalnızca BM25 fallback | 86.2% | 94.6% | 71.5% |
> Embedding modeli: `all-MiniLM-L6-v2` (yerel, ücretsiz, API anahtarı gerektirmez). Tam raporlar: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). Rakip karşılaştırması: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) — agentmemory'yi mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo ile karşılaştırır.
**Yerelde yeniden üretin:** [`eval/README.md`](../eval/README.md), LongMemEval `_s` (herkese açık 500 soru) + `coding-agent-life-v1` (şirket içi 15-oturumluk corpus) için adaptör-takılabilir bir harness. Grep / vektör / agentmemory adaptörleri yan yana puanlanır, NDJSON çıktısı verir, yayımlanan scorecard'lar [`docs/benchmarks/`](../docs/benchmarks/) içine düşer.
**[codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything) ve [Graphify](https://github.com/safishamsi/graphify) ile eşleşir.** Kod-grafı indeksleme, çok-ajanlı build pipeline'ları ve doküman / PDF / görüntü / video genelinde daha geniş bilgi grafları. agentmemory yapılan işi hatırlar; bu üç proje, bağlam katmanının gerisini aydınlatır. Tarifler + soru-yönlendirme tablosu: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
---
agentmemory
mem0 (63K ⭐)
Letta / MemGPT (24K ⭐)
Khoj (36K ⭐)
supermemory (29K ⭐)
TencentDB Agent Memory (22K ⭐)
MemPalace (54K ⭐)
oracleagentmemory
Hippo
Yerleşik (CLAUDE.md)
Tür
Bellek engine'i + MCP sunucusu
Bellek katmanı API'si
Tam ajan runtime'ı
Kişisel AI
Bellek API'si + uygulama
Takım belleği hub'ı (LLM proxy)
Vektör belleği (OSS)
Bellek engine'i (Oracle DB)
Bellek sistemi
Statik dosya
Geri Getirme R@5
95.2%
68.5% (LoCoMo)
83.2% (LoCoMo)
N/A
Kendi beyanı
PersonaMem 76% (kendi beyanı)
~96.6% (kendi beyanı)
94.4% (kendi beyanı)
N/A
N/A (grep)
Otomatik yakalama
12 hook (sıfır manuel çaba)
Manuel add() çağrıları
Ajan kendi kendine düzenler
Manuel
API tarafında çıkarım
Proxy ile yakalama (base-URL değişimi)
Manuel
API çıkarımı
Manuel
Manuel düzenleme
Arama
BM25 + Vektör + Graf (RRF füzyonu)
Vektör + Graf
Vektör (arşivsel)
Semantik
Vektör + RAG
4 varlık türü (Chat / Skill / Wiki / CodeGraph)
Yalnızca vektör
Vektör + semantik
Çürüme ağırlıklı (decay-weighted)
Her şeyi bağlama yükler
Çoklu ajan
MCP + REST + lease'ler + signal'ler
API (koordinasyon yok)
Yalnızca Letta runtime'ı içinde
Hayır
Hayır
Takım rolleri + paylaşılan varlıklar
Hayır
Yalnızca scope'lu
Çoklu ajan arasında paylaşılan
Ajan başına dosyalar
Framework bağımlılığı (lock-in)
Yok (herhangi bir MCP istemcisi)
Yok
Yüksek (Letta kullanmak zorunlu)
Bağımsız
Yok
Proxy her model çağrısının önünde
Yok
Oracle Database
Yok
Ajan başına format
Harici bağımlılıklar
Yok (SQLite + iii-engine)
Qdrant / pgvector
Postgres + vektör DB
Birden fazla
Yönetilen bulut
Docker stack'i (Core + Hub + Proxy)
Vektör deposu
Oracle AI Database
Yok
Yok
Bellek yaşam döngüsü
4 katmanlı konsolidasyon + çürüme + otomatik unutma
Pasif çıkarım
Ajan tarafından yönetilen
Manuel
Otomatik unutma
Manuel inceleme; otomatik yönlendirme geliştiriliyor
Yok
Belirtilmemiş
Çürüme + konsolidasyon
Manuel budama
Token verimliliği
~1,900 token/oturum ($10/yıl)
Entegrasyona göre değişir
Çekirdek bellek bağlamda
Değişir
Bulut fiyatlandırması
Belirtilmemiş
Token bütçesi yok
LLM destekli (değişir)
Değişir
240 gözlemde 22K+ token
Gerçek zamanlı görüntüleyici
Evet (port 3113)
Bulut dashboard'u
Bulut dashboard'u
Web arayüzü
Bulut dashboard'u
Hub web arayüzü
Hayır
Hayır
Hayır
Hayır
Kendi sunucunda barındırma
Evet (varsayılan)
Opsiyonel
Opsiyonel
Evet
Hayır (yalnızca bulut)
Evet (Docker)
Evet
Evet (Oracle DB)
Evet
Evet
Benchmark notu: yalnızca agentmemory'nin R@5'i bizim kendi ölçtüğümüz sonuçtur (LongMemEval-S, benchmark/COMPARISON.md'dan yeniden üretilebilir). mem0 ve Letta rakamları, onların yayımladığı LoCoMo sayılarıdır (farklı bir veri kümesi); MemPalace, supermemory, TencentDB (PersonaMem) ve oracleagentmemory rakamları, bağımsız olarak yeniden üretmediğimiz, satıcı tarafından kendi beyan edilen iddialardır (oracleagentmemory'nin çalıştırması bir Oracle AI Database'e karşı GPT-5.5 kullandı). Yalnızca kabaca karşılaştırma için yan yana gösterilmiştir, aynı veri üzerinde doğrudan bir karşılaştırma değildir. Yıldız sayıları yaklaşıktır ve zamanla değişir.
**Bilinmesi gereken daha yeni oyuncular**, [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) içinde derinlemesine karşılaştırılmıştır:
| Sistem | ⭐ | Yaklaşım |
|--------|---|-------|
| Zep / Graphiti | 30K | Temporal bilgi grafı; yayımlanmış en güçlü temporal-sorgu sonuçları (LongMemEval 63.8%), ancak graf asenkron olarak oluşturulur, bu yüzden yeni bilgiler gecikebilir |
| Cognee | 30K | Doküman-to-bilgi-grafı alımı, yalnızca Python, oturum yakalamadan ziyade yapılandırılmış entity çıkarımı için inşa edilmiştir |
Bunların hiçbiri kodlama-ajanı hook'larından otomatik yakalama yapmaz, local-first bir görüntüleyici sunmaz veya anahtarsız çalışmaz — agentmemory'nin etrafında inşa edildiği kombinasyon budur.
---
Uyumluluk: bu sürüm `iii-sdk` 0.22.1'i hedefler ve iii-engine v0.22.1'i sabitler.
### 30 saniyede deneyin
```bash
# 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 REST'i, health'i, görüntüleyiciyi ve iii destekli runtime durumunu doğrulayın:
```bash
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
```
Başlangıç hazır paneli, dört portun tümünü hesaba katar: 3111'de REST/MCP HTTP, 3112'de iii stream'leri, 3113'te görüntüleyici ve 49134'te iii worker WebSocket'i. `status`, agentmemory sağlığını ve etkin sağlayıcı/embedding modunu doğrular. Bir probe kaydedin ve aranabilir olduğunu doğrulayın:
```bash
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
-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 '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](#install) bölümünde (ilk çalıştırma sizi adım adım yönlendirir). Günlük kullanımda:
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
agentmemory connect # 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:
```bash
# 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 seçicisinde yerli (native) oturumların yanında görünür. Arka planda her giriş, yan kanal sunucu olmadan `mem::replay::load`, `mem::replay::sessions` ve `mem::replay::import-jsonl` iii fonksiyonları üzerinden yönlendirilir. İçe aktarılan her transkript arama için indekslenir, `import` köken kanalıyla damgalanır ve bir oturum kristali ile dersler için madenden geçirilir.
> **`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:
```bash
npx -y @agentmemory/agentmemory@latest upgrade
```
Uyarı: bu komut mevcut workspace/runtime'ı değiştirir. JavaScript bağımlılıklarını güncelleyebilir ve sabitlenmiş `iiidev/iii:0.22.1` Docker imajını çekebilir. Asla sabitlenmemiş veya daha yeni bir iii engine kurmaz.
Uygulama detayları `src/cli.ts` içinde yaşar (`src/cli.ts:544-595` bölgesindeki `runUpgrade`'e bakın).
### Claude Code (tek blok, yapıştırın)
```text
Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. 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:
```bash
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)
```bash
# 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](../docs/plugins/codex-local.md) 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`](https://github.com/openai/codex/blob/main/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:
```bash
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](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions) bakın. CLI connector'ı VS Code'u yapılandırmaz.
```bash
# 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.
OpenClaw (bu prompt'u yapıştırın)
```text
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/`](../integrations/openclaw/)
Hermes Agent (bu prompt'u yapıştırın)
```text
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/`](../integrations/hermes/)
### Diğer ajanlar
Bellek sunucusunu başlatın: `npx -y @agentmemory/agentmemory@latest`
#### `npx skills add` ile yerel skill'ler (50+ ajan)
agentmemory, Claude-Code-tarzı `/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`](https://npmjs.com/package/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:
```bash
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 `'ı **tamamlayıcı** niteliktedir:
- `agentmemory connect `, tool'ların kullanılabilir olması için MCP sunucu yapılandırmasını yazar.
- `npx skills add rohitg00/agentmemory`, ajanın onları ne zaman çağıracağını bilmesi için skill'leri 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ğu**dur:
```json
"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/` | Cursor Marketplace listesi (başvuru incelemede) veya Cursor Settings → Plugins → yerel checkout. 7 otomatik yakalama hook'u (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skill + MCP sunucusunu kaydeder; `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET`, Cursor'un eklenti dashboard'unda yönetilir. Cursor IDE'de ve `cursor-agent` CLI'sinde çalışır; CLI print-mode prompt'ları, oturum sonunda oturum transkriptinden geriye doldurulur (backfill). |
| **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:` 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/`](../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`](../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ı](../docs/plugins/codex-local.md). |
| **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`](../plugin/opencode/README.md)'a bakın. |
| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi`, paketlenmiş eklentiyi pi'nin otomatik keşif dizinine kurar (ajan başlangıcında recall, ajan sonunda yakalama, `memory_search` / `memory_save` / `memory_health` tool'ları, `/agentmemory-status`). Çalışan bir pi'de `/reload` bunu alır. [`integrations/pi`](../integrations/pi/), aynı zamanda bir pi paketidir (bir checkout'tan `pi install ./integrations/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`](../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ı](../docs/plugins/antigravity.md). |
| **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ı](../docs/plugins/antigravity.md). |
| **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 8 agentmemory skill'i (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`), Warp'ın slash-komut paletinde yerli olarak görünür. |
| **Cline (CLI)** | `~/.cline/mcp.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`, ikisi de yoksa `config.yaml`'ı sıfırdan oluşturur veya mevcut `config.json`'u değiştirir. **Zaten bir `config.yaml`'ınız varsa**, adaptör `mcpServers:` altına yapıştırılacak tam bloğu yazdırır; yaml'ınızı sessizce yeniden yazmaz, çünkü yorumları ve anchor'ları güvenle korumak, paketin birlikte gelmediği bir YAML parser'ı gerektirir. Continue, `mcpServers` için dizi biçimini (nesne değil) 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 `/.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`, her Harness profilinin yüklediği ev-seviyesi (home-level) patch katmanına bir `@deepseek-ai/dsh-mcp-client` satırı ekler; tool'lar `mcp__agentmemory__*` olarak kaydolur. Otomatik yakalamayı da bağlamak için `--with-hooks` geçirin: paketlenmiş Claude Code hook scriptleri, `$DSH_HOME/agentmemory.hooks.json`'a yazılan bir manifest aracılığıyla Harness'ın birinci taraf `@deepseek-ai/dsh-hooks-claude-code` köprüsü üzerinden çalışır (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop). `DSH_HOME` ayarsızken varsayılan olarak `~/.dsh` kullanılır. |
| **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 | REST API ile doğrudan konuşun: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
| **Herhangi bir ajan (32+)** | yok | `npx skillkit install agentmemory`, host'u otomatik algılar ve birleştirir. |
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)
agentmemory, çekirdek işlemlerini iii fonksiyonları olarak kaydeder (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). iii SDK'sı olan herhangi bir dil, bunları doğrudan `ws://localhost:49134` üzerinden çağırabilir; dil başına ayrı bir REST istemcisi gerekmez.
```bash
pip install iii-sdk # Python
cargo add iii-sdk # Rust
npm install iii-sdk # Node
```
```python
from iii import register_worker
iii = register_worker("ws://localhost:49134")
iii.connect()
iii.trigger({
"function_id": "mem::smart-search",
"payload": {"project": "demo", "query": "how do tokens refresh"},
})
```
Çalışan örnek: [`examples/python/`](../examples/python/) (quickstart + gözlem/recall akışı). `:3111` üzerindeki REST, iii runtime'ı olmayan host'lar için kullanılabilir olmayı sürdürür.
### Kaynaktan
```bash
git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start
```
Bu, sabitlenmiş binary zaten kuruluysa agentmemory'yi yerel bir `iii-engine` ile başlatır, veya seçildiğinde Docker Compose kullanır. REST, stream'ler ve görüntüleyici, varsayılan olarak `127.0.0.1`'e bağlanır. Otomatik macOS/Linux binary yolu, `curl`, bir POSIX `sh` ve `tar` gerektirir.
`iii-engine`'i manuel olarak kurun. **agentmemory şu anda `iii-engine`'i `v0.22.1`'e sabitler**, bu `iii-sdk` bağımlılığıyla aynı sürümdür; worker, bu engine'in wire protokolünü konuşur ve 0.20.0, SDK yüzeyini yeniden düzenledi, bu yüzden ikisi agentmemory sürümlerinde birlikte hareket eder. Kendi engine'inizi çalıştırıyorsanız ve eşleştiğini biliyorsanız `AGENTMEMORY_III_VERSION=` ile geçersiz kılın.
- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
- **macOS x64:** `aarch64-apple-darwin`'i `x86_64-apple-darwin` ile değiştirin
- **Linux x64:** `x86_64-unknown-linux-gnu` ile değiştirin
- **Linux arm64:** `aarch64-unknown-linux-gnu` ile değiştirin
- **Windows:** [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1)'den `iii-x86_64-pc-windows-msvc.zip`'i indirin ve `iii.exe`'yi `%USERPROFILE%\.agentmemory\bin\iii.exe`'ye çıkarın
Her arşivin release sayfasında eşleşen bir `.sha256` dosyası vardır; platformu değiştirdiğinizde, yukarıdaki kontrolde o dosyanın hash'ini kullanın (Windows'ta: `Get-FileHash`). `npx @agentmemory/agentmemory` içindeki otomatik installer, bu hash'leri sabitler ve eşleşmeyen bir arşivi reddeder.
Veya Docker kullanın (paketlenmiş `docker-compose.yml`, `iiidev/iii:0.22.1`'i çeker). Tam dokümantasyon: [iii.dev/docs](https://iii.dev/docs).
### Windows
agentmemory, Windows 10/11'de çalışır, ancak yalnızca Node.js paketi yeterli değildir; ayrıca arka plan süreci olarak sabitlenmiş iii-engine v0.22.1 runtime'ına da ihtiyacınız vardır. CLI, Windows ZIP'ini otomatik olarak çıkarmaz, bu yüzden yerel Windows kullanıcıları `iii.exe`'yi manuel olarak kurmalı, WSL2 kullanmalı veya Docker Desktop'ı seçmelidir.
Yerel Windows'ta otomatikleştirilmiş MCP bağlama, yalnızca `agentmemory connect copilot-cli`'yi destekler. Claude Code, Codex, Cursor ve diğer tüm yerel Windows ajanları için, [Diğer ajanlar](#other-agents) bölümündeki manuel MCP bloğunu o ajanın Windows yapılandırmasına kopyalayın. WSL içinde `connect` çalıştırmak, yalnızca hedef ajan aynı WSL ortamında da kuruluysa uygundur; bir Windows-host ajanının yapılandırmasını düzenlemez.
**Seçenek A: önceden derlenmiş (prebuilt) Windows binary (önerilen)**
```powershell
# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
# (agentmemory pins the engine to the same release as its iii-sdk;
# v0.22.1 is the current pair)
# 2. Download iii-x86_64-pc-windows-msvc.zip
# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
# 3. Extract iii.exe to agentmemory's private engine directory:
New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
# 4. Verify:
& "$HOME\.agentmemory\bin\iii.exe" --version
# Should print: 0.22.1
# 5. Then run agentmemory as usual:
npx -y @agentmemory/agentmemory@latest
```
**Seçenek B: Docker Desktop**
```powershell
# 1. Install Docker Desktop for Windows
# 2. Start Docker Desktop and make sure the engine is running
# 3. Select Docker explicitly and run agentmemory:
$env:AGENTMEMORY_USE_DOCKER = "1"
npx -y @agentmemory/agentmemory@latest
```
**Seçenek C: yalnızca bağımsız MCP (engine olmadan).** Ajanınız için yalnızca MCP tool'larına ihtiyacınız varsa ve REST API'ye, görüntüleyiciye veya cron job'larına gerek yoksa, engine'i tamamen atlayın:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
# or via the shim package:
npx -y @agentmemory/mcp
```
**Windows için diagnostik:** `npx -y @agentmemory/agentmemory@latest` başarısız olursa, gerçek engine stderr'ini görmek için `--verbose` ile yeniden çalıştırın. Yaygın hata modları:
| Belirti | Çözüm |
|---|---|
| `The engine process started but the REST API never responded.` | Türetilen dört portun da boş olduğunu doğrulayın, sabitlenmiş `iii.exe`'nin hayatta kaldığını kontrol edin, ardından `--verbose` ile yeniden çalıştırın ve yakalanan engine stderr'ini inceleyin |
| `Could not start iii-engine` | Ne `iii.exe` ne de Docker kurulu. Yukarıdaki Seçenek A veya B'ye bakın |
| Port çatışması | Neyin bağlı olduğunu görmek için `netstat -ano \| findstr :3111`, ardından onu sonlandırın veya `--port ` kullanın |
| Docker kurulu olsa bile Docker fallback'i atlanıyor | Docker Desktop'ın gerçekten çalıştığından emin olun (sistem tepsisi simgesi) |
> Not: iii **engine**'i önceden derlenmiş bir binary'dir, bir cargo crate değildir, bu yüzden onu `cargo install` ile kurmaya çalışmayın. (iii **SDK'ları** crates.io, npm ve PyPI'de yayımlanır, ancak agentmemory bunlara ihtiyaç duymaz.) Desteklenen engine kurulum yöntemlerinin tümü v0.22.1'e sabitlenmiştir: yukarıdaki önceden derlenmiş binary, agentmemory'nin macOS/Linux otomatik kurulum yolu (`curl`, POSIX `sh` ve `tar` gereklidir) ve Docker imajı `iiidev/iii:0.22.1`. Düz bir upstream `install.sh | sh`, agentmemory'nin desteklemediği en son engine'i kurar. `npx -y @agentmemory/agentmemory@latest` kullanın; macOS/Linux'ta sabitlenmiş engine'i `~/.agentmemory/bin` içine getirir.
---
Deploy
Yönetilen host'lar için tek tıkla şablonlar. Her biri, npm'den `@agentmemory/agentmemory`'i çeken ve iii engine binary'sini resmi `iiidev/iii` Docker Hub imajından kopyalayan kendi kendine yeten (self-contained) bir Dockerfile gönderir; önceden derlenmiş bir agentmemory imajı gerekmez. Kalıcı depolama `/data`'ya mount edilir; ilk-boot entrypoint'i, npm ile paketlenmiş iii yapılandırmasını (`127.0.0.1`'e bağlanan) `0.0.0.0`'a bağlanan ve absolute `/data` path'leri kullanan, HMAC secret'ını üreten, dağıtıma özel (deploy-tuned) bir yapılandırmayla değiştirir; ardından agentmemory CLI'sini exec etmeden önce `gosu` üzerinden `root`'tan `node`'a ayrıcalıkları düşürür.
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/`](.././deploy/render/README.md) 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/`](.././deploy/README.md) içinde yaşar:
- [`deploy/fly`](.././deploy/fly/README.md): `auto_stop_machines = "stop"` ile tek
makine; en ucuz boşta kalma (idle).
- [`deploy/railway`](.././deploy/railway/README.md): Hobby plan sabit ücret,
dashboard'da volume.
- [`deploy/render`](.././deploy/render/README.md): Blueprint akışı,
ücretli planlarda otomatik disk snapshot'ları.
- [`deploy/coolify`](.././deploy/coolify/README.md): [Coolify](https://coolify.io/self-hosted) ile kendi
VPS'inizde self-hosted; aynı Docker Compose stack'i, host'a ve veriye siz sahip olursunuz.
Yalnızca port `3111` yayımlanır. `3113`'teki görüntüleyici container içinde
loopback'e bağlı kalır; her şablonun README'si, ona erişmek için
SSH-tüneli desenini belgeler.
---
Her kodlama ajanı, oturum sona erdiğinde her şeyi unutur ve her yeni oturum, stack'inizi yeniden açıklamanızla başlar. agentmemory arka planda çalışır ve bu adımı kaldırır.
```text
Session 1: "Add auth to the API"
Agent writes code, runs tests, fixes bugs
agentmemory silently captures every tool use
Session ends -> observations compressed into structured memory
Session 2: "Now add rate limiting"
Agent already knows:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
Zero re-explaining. Starts working immediately.
```
### 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 |
|---|---|---|
| Ölçek | 200 satır sınırı | Sınırsız |
| Arama | Her şeyi bağlama yükler | BM25 + vektör + graf (yalnızca top-K) |
| Token maliyeti | 240 gözlemde 22K+ | ~1,900 token (92% daha az) |
| 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'ı
```text
PostToolUse hook fires
-> SHA-256 dedup (5min window)
-> 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 SLOT_REFLECT_ENABLED=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
-> Inject into conversation
```
### 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
| 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** | Her tool kullanımı hook'lar üzerinden kaydedilir, manuel çaba yok |
| **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, `` 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.
Vektörler bir çökme veya force-kill'den sağ çıkar. Vektör indeksi, en fazla her `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS`'de (10 dakika) bucket'lar halinde kaydedilir. Bu aralıkta eklenen veya kaldırılan her vektör, state store'daki küçük bir bekleyen (pending) log'a da hemen yazılır ve bir sonraki başlatma, embedding sağlayıcısını çağırmadan bunu replay eder. Her başarılı kayıt, log'u boşaltır. Replay'den sonra hâlâ vektörü olmayan dokümanlar, hiçbiri kalmayana kadar `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) parti halinde arka planda yeniden embed edilir ve durdurulan bir backfill, bir sonraki başlatmada devam eder. `/agentmemory/status` ve görüntüleyici, bekleyen log boyutunu ve backfill durumunu gösterir. Anahtarsız kurulumlar hiçbir şey yazmaz.
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:
```env
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 | İlk model indirmesinden sonra cihaz üzerinde, yalnızca BM25'e göre +8pp recall |
| 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](https://ai.google.dev/gemini-api/docs/deprecations)) |
| OpenAI | `text-embedding-3-small` | $0.02/1M | En yüksek kalite |
| 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/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:
```bash
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):
```json
{
"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`):
```json
{
"mcp": {
"agentmemory": {
"type": "local",
"command": ["npx", "-y", "@agentmemory/mcp"],
"enabled": true
}
},
"plugin": ["./plugins/agentmemory-capture.ts"]
}
```
Eklenti dosyasını repo'dan kopyalayın:
```bash
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/`, `#sessions/?obs=`, `#graph/`, `#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.
```bash
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'`).
---
`:3113`'teki görüntüleyici, ajanınızın **hatırladığını** gösterir. [iii console](https://iii.dev/docs/console), ajanınızın **yaptığını** gösterir: her bellek işlemi bir OpenTelemetry trace'i olarak, her KV girdisi düzenlenebilir, her fonksiyon çağrılabilir, her stream dinlenebilir (tappable). Aynı belleğe iki pencere: biri ürün şekilli, biri engine şekilli.
Bir `memory_smart_search`'ün ateşlenmesini izleyin ve BM25 taraması → embedding lookup'u → RRF füzyonu → reranker'ı bir waterfall olarak görün. KV browser'da takılı kalmış bir konsolidasyon timer'ını düzenleyin. Değiştirilmiş bir payload ile bir `PostToolUse` hook'unu yeniden oynatın (replay). WebSocket stream'ini pin'leyin ve gözlemlerin canlı olarak düşmesini izleyin.
agentmemory, bunu ücretsiz olarak sunar çünkü her fonksiyon çağrısı ve trigger iii üzerinden ateşlenir; özel (custom) hiçbir şey yok, enstrümante edilecek hiçbir şey yok.
Workers sayfası: agentmemory'nin kendisi dahil her bağlı worker; PID, fonksiyon sayısı, runtime ve son-görülme ile birlikte.
**Zaten kurulu.** Console, sabitlenmiş `iii` engine'i (0.22+) ile birlikte gelir; ayrıca kurulacak bir şey yok. İlk başlatma, console binary'sini engine'in yanına indirir.
**agentmemory ile birlikte başlatın:**
```bash
agentmemory console
```
Bu, sabitlenmiş engine'in `iii console`'unu agentmemory'nin çözümlediği portlara (REST, stream'ler, bridge) karşı çalıştırır ve bunu görüntüleyicinin bir port üstünde, varsayılan olarak `http://localhost:3114`'te sunar. `--console-port N`, başka bir port seçer; `--port` ve `--instance`, `stop` için yaptıkları gibi agentmemory instance'ını seçer; başka herhangi bir flag geçirilir, örneğin deneysel mimari-grafı sayfası için `--enable-flow`.
Aynı şeyi elle yapmak, `agentmemory` PATH'te olmadığında kullanışlıdır:
```bash
~/.agentmemory/bin/iii console --port 3114 \
--engine-port 3111 \
--ws-port 3112 \
--bridge-port 49134
```
**Console'dan yapabilecekleriniz:**
| Sayfa | Şunun için kullanın |
|------|-----------|
| **Workers** | agentmemory worker'ının kendisi dahil, bağlı her worker'ı ve canlı metriklerini görün. |
| **Functions** | agentmemory'nin fonksiyonlarından herhangi birini bir JSON payload ile doğrudan çağırın; bir istemci bağlamadan `memory.recall`, `memory.consolidate`, `graph.query`'yi test etmek için kullanışlıdır. |
| **Triggers** | HTTP, cron, event ve state trigger'larını yeniden oynatın: konsolidasyon cron'unu manuel olarak ateşleyin, bir HTTP route'unu yeniden deneyin, bir state değişikliği yayınlayın. |
| **States** | Oturumlar, bellek slot'ları, yaşam döngüsü timer'ları ve embedding indeksi üzerinde tam CRUD'a sahip KV browser; değerleri yerinde düzenleyin. |
| **Streams** | iii stream'leri üzerinden akarken bellek yazmaları, hook olayları ve gözlem güncellemeleri için canlı WebSocket monitörü. |
| **Queues** | Dayanıklı (durable) queue topic'leri + dead-letter yönetimi. Başarısız embedding / compression job'larını yeniden oynatın veya düşürün. |
| **Traces** | OpenTelemetry waterfall / flame / service-breakdown görünümleri. Tek bir `memory.search`'ün tam olarak hangi fonksiyonları, DB çağrılarını ve embedding isteklerini ürettiğini görmek için `trace_id`'ye göre filtreleyin. |
| **Logs** | trace/span ID'leriyle filtrelenen ve ilişkilendirilen yapılandırılmış OTEL log'ları. |
| **Config** | Runtime yapılandırması: engine'inizin tam olarak hangi worker'larla, sağlayıcılarla ve portlarla çalıştığını görün. |
| **Flow** | (Opsiyonel, `--enable-flow`) Her worker, trigger ve stream'in interaktif mimari grafı. |
Traces: her bellek işlemi için waterfall / flame / service breakdown.
**Trace'ler zaten açık:**
`iii-config.yaml`, `iii-observability` worker'ı etkinleştirilmiş şekilde gelir (`exporter: memory`, `sampling_ratio: 0.1`, metrikler + log'lar). Ekstra yapılandırmaya gerek yoktur; agentmemory başladığı anda, her bellek işlemi console'un okuyabileceği yapılandırılmış bir log yayar ve bunların onda biri (`sampling_ratio: 0.1`) ayrıca bir trace span'ı da yayar.
Bunun yerine Jaeger/Honeycomb/Grafana Tempo'ya export etmek isterseniz, `exporter: memory`'yi `exporter: otlp` olarak değiştirin ve collector endpoint'ini iii'nin observability dokümantasyonuna göre ayarlayın.
> **Dikkat:** console'un kendisinde auth zorunlu değildir; onu `127.0.0.1`'e bağlı tutun (varsayılan) ve asla herkese açık hale getirmeyin.
---
agentmemory, **zaten çalışan bir [iii](https://iii.dev) instance'ıdır**. Üç primitif (worker, function, trigger) runtime'ı oluşturur; KV state, stream'ler ve OTEL trace'leri, iii ile birlikte gelen iii-state, iii-stream ve iii-observability worker'larından gelir. Postgres, Redis, Express, pm2 veya Prometheus kurmadınız, çünkü iii bunların yerini alır.
Bu, bir komut daha ile agentmemory'yi tamamen yeni bir yetenekle genişletebileceğiniz anlamına gelir.
### agentmemory'yi daha fazla worker ile genişletin
agentmemory'nin ihtiyaç duyduğu builtin'ler zaten `iii-config.yaml` içindedir ve onunla birlikte boot olur: `iii-state` (KV), `iii-queue` (event subscriber'lar için dayanıklı retry'ler), `iii-pubsub`, `iii-cron`, `iii-stream` ve `iii-observability` (her fonksiyonda OTEL trace'leri, metrikler ve log'lar). [iii worker registry](https://workers.iii.dev)'den başka herhangi bir şey aynı engine'e takılır: `iii-config.yaml`'ı `~/.agentmemory/iii-config.yaml`'a kopyalayın (CLI, bu dosyayı paketlenmiş olana tercih eder ve hâlâ portları ve veri path'lerini bunun içine render eder), girdiyi ekleyin, worker runtime'ını bir kez `~/.agentmemory/bin/iii update worker` ile kurun ve agentmemory'yi yeniden başlatın.
```yaml
workers:
# ...the bundled entries...
- name: database # SQL-backed state adapter when you outgrow the KV defaults
- name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
- name: mcp # extra MCP servers next to agentmemory's, same engine
```
| Worker | agentmemory'nin üstüne ne eklenir |
|---|---|
| [`database`](https://workers.iii.dev/workers/database) | Bellek içi (in-memory) KV varsayılanlarını aştığınızda SQL destekli state adaptörü |
| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | `memory_recall`'dan çıkan kod, shell'inizde değil, tek kullanımlık (throwaway) bir VM içinde çalışır |
| [`mcp`](https://workers.iii.dev/workers/mcp) | agentmemory'ninkinin yanında ek MCP sunucuları kurun, aynı engine'i paylaşın |
Engine 0.22.x'te, yukarıdaki builtin'ler için `iii-` önekli adları koruyun; önek olmayan `http`, `state`, `queue`, `pubsub` ve `cron` girdileri, agentmemory'nin 0.23 migrasyonuyla geçeceği bağımsız registry worker'larıdır.
Tam registry: [workers.iii.dev](https://workers.iii.dev). Oradaki her worker, agentmemory'nin kullandığı aynı primitifler üzerinden compose olur ve zaten sahip olduğunuz agentmemory onlardan biridir.
### Engine config ve bind adresi
`agentmemory start`, engine config'ini var olan ilk dosyadan okur: `AGENTMEMORY_III_CONFIG`, geçerli dizindeki `./iii-config.yaml`, `~/.agentmemory/iii-config.yaml`, ardından paketlenmiş `iii-config.yaml`. Her başlatmada o dosyayı (veri path'leri, portlar, state backend'i) `~/.agentmemory/data/iii-config.runtime.yaml`'a render eder ve engine'i render edilmiş kopyayla başlatır, bu yüzden kaynak dosyayı düzenleyin, render edilmiş olanı değil. Kaynak dosyanın `host:` değerleri, yazıldığı gibi korunur.
Paketlenmiş `iii-config.yaml`, kasıtlı olarak `127.0.0.1`'e bağlanır ve bu varsayılan, bir container içinde de geçerlidir. Bir container'da başlatılan bir CLI, container'ın loopback'ini dinler, bu yüzden yayımlanan portlar hiçbir şeye erişemez. Container'lanmış bir CLI'yi yayımlanan portlar üzerinden servis etmek için, `AGENTMEMORY_III_CONFIG`'i `0.0.0.0`'a bağlanan bir config'e ayarlayın. Paketlenmiş `iii-config.docker.yaml` bunlardan biridir: `iii-http`'yi, `iii-stream`'i ve engine portunu `0.0.0.0`'a bağlar ve state'i `/data` altında saklar, bu yüzden oraya yazılabilir bir volume mount edin. `AGENTMEMORY_SECRET`'ı ayarlı tutun ve yalnızca ihtiyacınız olan portları, `127.0.0.1`'de veya güvendiğiniz bir proxy'nin arkasında yayımlayın.
Bu repo'nun `docker-compose.yml`'i, CLI'nin config lookup'ından geçmez: `iii-config.docker.yaml`'ı `/app/config.yaml`'a mount eder ve `iii-engine` container'ı `--config /app/config.yaml` ile başlar. Tek tıkla [deploy şablonları](../deploy/), entrypoint'lerinde kendi `0.0.0.0` config'lerini yazar.
### Depolama backend'i: file (varsayılan) vs redis
`iii-state` ve `iii-stream`, varsayılan olarak iii-engine'in paketlenmiş dosya tabanlı KV deposunu kullanır: scope başına bir JSON dosyası, engine sürecinin belleğinde tutulur ve bir timer'da diske yeniden yazılır. Bu, tek kullanıcılı yerel bir kurulum için doğru varsayılandır; birden fazla eşzamanlı yazıcıya sahip paylaşılan bir daemon, bunun yerine Redis'ten gerçek key-başına yazmalar alır, işlem başına bir network round trip maliyetiyle (her `state::*` çağrısı hâlâ tek bir Redis bağlantısında serileşir, bu yüzden bu, dosya deposunun lock'unu bir socket ile değiştirir, paralellik ile değil).
Her iki worker'ı da, her yazmada tüm bir scope'u yeniden yazmak yerine her key'i bir Redis hash field'ı (`HSET`) olarak saklayan iii-engine'in yerleşik `redis` adaptörüne geçirmek için `AGENTMEMORY_STATE_BACKEND=redis`'i (artı `AGENTMEMORY_REDIS_URL`'i) ayarlayın:
```env
# ~/.agentmemory/.env
AGENTMEMORY_STATE_BACKEND=redis
AGENTMEMORY_REDIS_URL=redis://localhost:6379
```
`AGENTMEMORY_STATE_BACKEND`, varsayılan olarak `file`'dır; ayarlanmamış bırakmak bugünkü davranışı değiştirmeden tutar ve tanınmayan bir değer (`file` veya `redis` dışında herhangi bir şey), sessiz bir fallback yerine bir başlatma hatasıdır. `/agentmemory/status` ve görüntüleyicinin Health sayfası (State store satırı), hangi backend'in aktif olduğunu ve yanıt verip vermediğini bildirir, URL'i asla.
**Yalnızca düz `redis://`.** Sabitlenmiş engine (0.22.1), Redis istemcisini TLS desteği olmadan derler, bu yüzden bir `rediss://` URL'i (Upstash, Redis Cloud ve transit sırasında şifrelemeyle ElastiCache gibi çoğu yönetilen Redis teklifi, varsayılan olarak yalnızca-TLS'tir) bağlanamaz. Bağlantı şifrelenmemiştir, bu yüzden Redis şifresi ve saklanan her bellek, kabloda açık metin olarak geçer: yerel bir Redis'e veya güvendiğiniz özel bir ağdaki bir Redis'e işaret edin. Başka herhangi bir Redis için, agentmemory host'unda şifrelenmiş bir tünel (stunnel, SSH veya bir VPN) çalıştırın, böylece düz `redis://` sıçraması o host'ta kalır ve tünelin upstream bağlantısı şifrelenir ve kimlik doğrulanır (authenticated). Bir Redis şifresi tek tırnak içeriyorsa, onu percent-encode edin (`%27`); engine, URL'i parse etmeden önce YAML config'ine genişletir.
**`--instance` başına bir Redis sunucusu.** Engine'in Redis key önekleri (`state:`, `stream::`) sabittir, bu yüzden aynı database'e işaret eden iki agentmemory instance'ı (`--instance 1`, `--instance 2`, ...) birbirinin verisinin üzerine yazar. Ayrı bir database index'i (`redis://localhost:6379/1`), saklanan veriyi ayrı tutar, ancak engine canlı görüntüleyici olaylarını tek bir Redis pub/sub kanalı (`stream::events`) üzerinden iletir ve Redis pub/sub, database index'ini yok sayar, bu yüzden her instance'ın görüntüleyicisi hâlâ diğerinin canlı olaylarını gösterir. Birden fazla instance çalıştırdığınızda her birine kendi Redis sunucusunu (veya portunu) verin.
**Ne aynı kalır, ne farklıdır.** Her agentmemory özelliği Redis üzerinde çalışır: oturumlar, gözlemler, bellekler (remember, supersede, evolve, forget), arama ve indeks bucket'ları, dersler, graf, audit log'u ve onun aylık scope'ları, export ve import, governance delete'leri, konsolidasyon durumu, görüntüleyici snapshot'ı ve canlı stream'i, ve health monitor'u. Engine, her scope'u tek bir Redis hash'i (`HSET`/`HGET`/`HGETALL`) olarak saklar ve dosya deposuyla aynı state trigger'larını ateşler. Üç engine farkı agentmemory içinde ele alınır:
- Redis, bir scope'un kayıtlarını sabit bir sırada döndürmez. agentmemory bunları en eskiden başlayarak sıralar (önce record id'deki oluşturma zamanına, sonra timestamp'ine göre), bu yüzden list'ler, paging ve export chunk'ları dosya deposundaki aynı sırayla geri gelir.
- Engine, Redis üzerinde kısmi güncellemeleri, boş array'leri boş nesnelere çeviren bir Lua script'inde uygular. agentmemory, bu güncellemeleri Redis üzerinde kendisi uygular (key başına bir lock altında oku, değiştir, yaz), bu yüzden `tags: []` gibi field'lar array olarak kalır.
- Eski (legacy) audit log kontrolü, dosya deposunun diskteki dosyasını aramak yerine eski scope'u Redis'ten okur.
Bir fark sizi gerektirir: **Redis yeniden başladıktan sonra, engine, agentmemory yeniden başlayana kadar görüntüleyiciye canlı olayları iletmeyi durdurur.** Veri normal şekilde kaydedilir ve okunur. Health monitor, her 30 saniyede Redis üzerinden bir test olayı gönderir; geri gelmediğinde, `/agentmemory/status` ve görüntüleyicinin Health sayfası, çözümüyle birlikte "Canlı güncellemeler görüntüleyiciye ulaşmıyor" gösterir: agentmemory'yi yeniden başlatın. Redis kapalıysa, status raporu "State store yanıt vermiyor" ve onu nasıl kontrol edeceğinizi gösterir (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Çok büyük bir scope'u listelemek, tüm hash'i tek bir `HGETALL`'da okur; dosya deposunun bunu bellekte tutmasıyla aynı maliyettir.
**Önerilen Redis ayarları.** Varsayılan `save 3600 1 300 100 60 10000` snapshot politikası, bir çökmede dakikalarca yazmayı kaybedebilir; dosya deposunun 5 saniyelik flush penceresinden daha kötü. Kaybetmekten çekineceğiniz her şey için `appendonly yes` ayarlayın. `maxmemory-policy noeviction` ayarlayın; `allkeys-lru` veya benzeri, Redis bellek limitine ulaştığında bellekleri sessizce düşürür.
Native (Docker olmayan) bir başlatma ve her tek tıkla [deploy şablonu](../deploy/) (paketlenmiş `iii-config.yaml`'ın üzerine yazarlar ve native olarak başlarlar), `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL`'i okur ve bunları başlatılan `iii-config`'e render eder. URL'in kendisi o render edilmiş dosyaya asla yazılmaz, yalnızca engine sürecinin boot'ta kendi ortamından genişlettiği bir `${AGENTMEMORY_REDIS_URL}` referansı yazılır. Yalnızca bu repo'nun kendi Docker Compose yolu (`AGENTMEMORY_USE_DOCKER=1`, veya o şekilde zaten başlatılmış bir engine'i devam ettirmek), `iii-config.docker.yaml`'ı salt-okunur mount eder ve asla render etmez; `agentmemory start`, bu kombinasyonu algıladığında uyarır. O dosyayı elle değiştirin, [iii-state](https://workers.iii.dev/workers/iii-state) ve [iii-stream](https://workers.iii.dev/workers/iii-stream) worker dokümantasyonunda gösterilen aynı `name: redis` / `config: redis_url: ...` şeklini izleyerek ve `redis_url`'i container'dan erişilebilir bir Redis'e işaret edin. `docker-compose.yml`, `AGENTMEMORY_REDIS_URL`'i engine container'ına geçirir, bu yüzden `redis_url: '${AGENTMEMORY_REDIS_URL}'` orada çalışır ve URL'i mount edilmiş dosyanın dışında tutar.
Render edilmiş config, URL'i `~/.agentmemory/data/iii-config.runtime.yaml`'ın dışında tutar, ancak engine'in kendi yapılandırma worker'ı, boot olduğunda *genişletilmiş* değeri hâlâ `~/.agentmemory/config/iii-state.yaml` ve `iii-stream.yaml`'a kalıcı hale getirir (iii-engine'in `${VAR}` genişletmesi, o worker seed'ini saklamadan önce gerçekleşir ve çözümlenmiş değeri saklar, referansı değil). O dizini bir credential tutuyormuş gibi ele alın: herhangi bir paylaşılan host'ta `chmod 700 ~/.agentmemory` yapın ve database'in admin credential'ları yerine agentmemory'nin ihtiyaç duyduğuna scope'lanmış bir Redis ACL kullanıcısını tercih edin.
**Migrasyon otomatik değildir.** `AGENTMEMORY_STATE_BACKEND`'i değiştirmek, her iki tarafta da boş bir depodan başlar; hiçbir şey mevcut veriyi file'dan Redis'e veya geri kopyalamaz. Ayrıldığınız backend'den export edin ve taşındığınız backend'e import edin. Bu, bash ve zsh altında aynı şekilde çalışır (`bash -u` dahil). `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` gibi bir array çalışmaz: zsh, header'ı bash'in ikiye böldüğü yerde tek, hatalı biçimli (malformed) bir kelime olarak tutar, bu yüzden `AGENTMEMORY_SECRET` ayarlandığında her iki istek de 401 döner:
```bash
# 0. Use the generated secret when none is exported:
AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
# 1. On the old backend, while agentmemory is still running on it:
if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
else
curl -fsS http://localhost:3111/agentmemory/export > backup.json
fi
# 2. Confirm backup.json is a usable export before switching backends:
jq -e '.version and .exportedAt' backup.json > /dev/null || {
echo "backup.json is not a valid export; do not switch backends" >&2
exit 1
}
# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
# restart agentmemory against the new backend, then:
if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
-H 'Content-Type: application/json' -d @-
else
jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
curl -fsS -X POST http://localhost:3111/agentmemory/import \
-H 'Content-Type: application/json' -d @-
fi
```
`/agentmemory/export`, büyük bir corpus'u birden fazla çağrıya bölmek (chunking) için ayrıca `?maxSessions=` ve `?offset=` kabul eder; import'ta `strategy`, `merge` (varsayılan-güvenli), `replace` veya `skip`'tir.
### iii'nin yerini aldığı şeyler
| Geleneksel stack | agentmemory'nin kullandığı |
|---|---|
| Express.js / Fastify | iii HTTP Trigger'ları |
| SQLite / Postgres + pgvector | iii KV State + bellek içi vektör indeksi |
| SSE / Socket.io | iii Stream'leri (WebSocket) |
| pm2 / systemd | iii engine worker supervision'ı |
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom eklenti sistemleri | `iii worker add ` |
**219 kaynak dosya · ~52,000 LOC · 2,500+ test · 311 fonksiyon · 60 KV scope**, hepsi üç primitif üzerinde. `agentmemory plugin install` yok. Eklenti sistemi, iii'nin kendisidir.
---
### 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=` | OpenAI-API-uyumlu her şey. Sıfır maliyet, kendi hardware'inizde çalışır. Aşağıdaki [Yerel modeller](#local-models-ollama--lm-studio--vllm) 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`):
```bash
ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
ollama serve
```
```env
# ~/.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.).
```env
# ~/.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 (`` 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
Hem bir sağlayıcı hem de `AGENTMEMORY_AUTO_COMPRESS=true` ile LLM tarafından yazılan arka plan sıkıştırması etkinleştirildiğinde, her gözlemde çalışır, bu yüzden model seçimi aylık harcamayı anlamlı şekilde değiştirir. Yakalanan workload verisi: 2026-05-23 fiyatlandırmasıyla üç OpenRouter modeline karşı çalıştırılan 635 istek / 888K token / 35 saat aktif kullanım.
| Katman | Model | Girdi / 1M | Çıktı / 1M | Yakalanan 35 saat için maliyet | Notlar |
|------|-------|------------|-------------|---------------------------|-------|
| Önerilen | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (tah.) | En yeni DeepSeek; sıkıştırma workload'ları için önerilen en ucuz seçim. |
| Önerilen | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Sonnet'ten ~10× daha düşük maliyetle sağlam sıkıştırma + özetleme kalitesi. |
| Önerilen | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Oturumlarınız ağırlıklı olarak kod-şekilliyse güçlü kod reasoning'i. |
| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (tah.) | Ölçülen Sonnet 4.6 çalıştırmasıyla aynı liste fiyatı; 2026-08-31'e kadar $2/$10 giriş fiyatlandırması. |
| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (tah.) | Flagship katman; her zaman açık arka plan işi için maliyetli. |
| Kaçının | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (tah.) | Flagship sınıfı model; sıkıştırma için aşırı harcama. |
Ölçülen satırlar, yakalanan çalıştırmadan gelir; (tah.) satırları, aynı token karışımını her modelin liste fiyatıyla ölçekler.
agentmemory, `OPENROUTER_MODEL` bir premium-katman deseniyle eşleştiğinde bir runtime uyarısı yazdırır. Bilinçli bir seçim yaptıktan sonra sessize almak için `AGENTMEMORY_SUPPRESS_COST_WARNING=1` ayarlayın.
Bellek işi için kalite vs maliyet tradeoff'u: sıkıştırma, nispeten gevşek kalite çıtalarına sahip bir özetleme görevidir (özeti kullanıcı değil, ajan yeniden okur). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder, bu görevde Sonnet'in yuvarlama hatası içinde kalırken 10-70× daha az maliyete sahiptir. Premium katman modellerini, doğrudan okuduğunuz sorgular için saklayın.
Kaynaklar: [Claude Sonnet 5 için OpenRouter fiyatlandırması](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [DeepSeek fiyatlandırma notları](https://api-docs.deepseek.com/quick_start/pricing/).
### Ç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.
```env
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=` 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
agentmemory + iii-engine, varsayılan olarak dört port bağlar (bind). Bir yeniden başlatma `port in use` ile başarısız olursa, bu tablo hangi süreci arayacağınızı söyler.
| Port | Süreç | Amaç | Env override |
|------|---------|---------|--------------|
| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
| `3112` | iii-engine | Dahili stream worker'ı (agentmemory + görüntüleyici tarafından kullanılır) | `III_STREAM_PORT` (tercih edilen) veya legacy `III_STREAMS_PORT` |
| `3113` | agentmemory | Gerçek zamanlı görüntüleyici (`http://localhost:3113`) | Bildirilen URL için `III_VIEWER_PORT` veya `AGENTMEMORY_VIEWER_URL` |
| `49134` | iii-engine | WebSocket; worker'lar buraya kaydolur, OTel telemetrisi bunun üzerinden akar | `III_ENGINE_PORT` veya `III_ENGINE_URL` |
`--port `, REST anchor'ını değiştirir ve yalnızca yukarıdaki ilgili açık port veya URL ayarlanmamışsa stream'ler `N+1`, görüntüleyici `N+2` ve engine WebSocket'i `N+46023`'ü türetir. İzole bir lifecycle namespace'i oluşturmaz. İkinci bir daemon için `--instance 1` kullanın; bu, anchor 3211'i kullanır, varsayılan olarak `3211/3212/3213/49234`'tür ve ayrı bir `instance-1` veri ve lifecycle dizini alır. Instance 1'den 50'ye kadar aynı deseni izler.
Sabitlenmiş engine, `--no-update-check` ile başlar (boot'ta GitHub'a karşı güncelleme veya güvenlik-danışma aramaları yok) ve iii'nin anonim kullanım telemetrisi kapalıyken: değişkeni kendiniz export etmediğiniz sürece agentmemory, spawn ettiği engine için `III_TELEMETRY_ENABLED=false` ayarlar ve paketlenmiş compose dosyası da aynısını yapar.
Çökmüş bir çalıştırmadan sonra portlar bağlı kaldığında, bayatlamış (stale) süreç temizliği:
```bash
# macOS / Linux — find whatever is on each port and kill it
lsof -i :3111,3112,3113,49134
pkill -f agentmemory || true
pkill -f 'iii ' || true
# Windows
netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID
```
`agentmemory stop`, graceful native shutdown'da hem worker'ı hem de engine pidfile'ını temiz bir şekilde toplar (reap). Docker modunda, native worker'ı flush eder, tam olarak doğrulanmış engine container'ını durdurur ve kayıpsız bir yeniden başlatma için hem container'ı hem de `/data` mount'unu korur; bir sonraki başlatma, aynı container'ı doğrular ve devam ettirir. Docker destekli kaldırma, `agentmemory remove --keep-data` gerektirir: doğrulanmış container'ı, veri mount'unu ve onları kurtarmak için gereken lifecycle kaydını korurken paylaşılan agentmemory-yönetimli dosyaları kaldırır. Yıkıcı Docker veri silme işlemi, bir yedeklemeden sonra kasıtlı olarak operatöre bırakılmıştır. CLI, ayrıca `--force` geçirilmedikçe Docker veya VM port sahiplerini (Docker backend, vpnkit, colima) native engine olarak benimsemeyi veya sinyallemeyi reddeder. Yukarıdaki manuel temizlik, yalnızca hiçbir pidfile'ın kalmadığı çökme-sonrası durum içindir.
### Yapılandırma Dosyası
agentmemory runtime yapılandırmasını her shell'de değişken export etmek yerine `~/.agentmemory/.env` içine koyun. Görüntüleyici `export ANTHROPIC_API_KEY=...` gibi bir kurulum ipucu gösterirse, bunu `export` önekiyle olmadan `ANTHROPIC_API_KEY=...` olarak bu dosyaya kopyalayın, ardından agentmemory'yi yeniden başlatın.
Süreç ortam değişkenleri hâlâ çalışır ve dosyadaki değerlere göre önceliklidir.
Windows'ta, aynı dosya `%USERPROFILE%\.agentmemory\.env`'de yaşar:
```powershell
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:
```env
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:
```env
GRAPH_EXTRACTION_ENABLED=true
# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
```
### Ortam Değişkenleri
`~/.agentmemory/.env` dosyasını oluşturun:
```env
# LLM provider (pick one — default is the no-op provider: no LLM calls)
# ANTHROPIC_API_KEY=sk-ant-...
# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
# GEMINI_API_KEY=...
# OPENROUTER_API_KEY=...
# MINIMAX_API_KEY=...
# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
# # OpenAI LLM provider (here) AND the OpenAI
# # embedding provider (further below). Set
# # OPENAI_API_KEY_FOR_LLM=false to scope it
# # to embeddings only.
# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
# # Azure: https://.openai.azure.com/openai/deployments/
# # Auto-detected from `.openai.azure.com` hostname; uses
# # api-key header + api-version query param.
# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
# # for back-compat with v0.9.17. New configs should
# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
# # Honored only by OpenAI's reasoning models (o1, o3,
# # gpt-*-reasoning) and providers that mirror that
# # schema (Ollama Cloud thinking models). Standard
# # chat models reject this field with 400. Set to
# # "none" for thinking models that return reasoning
# # but no content.
# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
# # for LLM (useful if you only want OpenAI for embeddings)
# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
# Embedding provider (BM25-only when unset; local is an explicit opt-in)
# EMBEDDING_PROVIDER=local
# VOYAGE_API_KEY=...
# OPENAI_API_KEY=sk-...
# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
# Outbound LLM / embedding timeout
# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
# raw-fetch provider (Gemini, OpenRouter, MiniMax,
# OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
# embedding). For the OpenAI LLM path, the
# OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
# takes precedence when set, for back-compat
# with v0.9.17.
# Increase for slow networks or large batch calls;
# decrease to fail-fast on rate-limit holds.
# Search tuning
# BM25_WEIGHT=0.4
# VECTOR_WEIGHT=0.6
# TOKEN_BUDGET=2000
# Auth (generated into ~/.agentmemory/secret on first start when unset)
# AGENTMEMORY_SECRET=your-secret
# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
# AGENTMEMORY_IMPORT_ROOT=~/projects
# Ports (defaults: 3111 API, 3113 viewer)
# III_REST_PORT=3111
# Engine usage telemetry (iii). Off unless you set it; true opts in.
# III_TELEMETRY_ENABLED=false
# Features
# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
# provider as well. When both are on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
# token spend on active sessions.
# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
# memory slots — persona,
# user_preferences, tool_guidelines,
# project_context, guidance,
# pending_items, session_patterns,
# self_notes. Size-limited; agent
# edits via memory_slot_* tools.
# Pinned slots addressable for
# SessionStart injection.
# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
# Stop hook fires mem::slot-reflect:
# scans recent observations, auto-
# appends TODOs to pending_items,
# counts patterns in
# session_patterns, records touched
# files in project_context. Fire-
# and-forget; does not block.
# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
# - SessionStart may inject ~1-2K
# chars of project context into
# the first turn of each session
# (this is what actually reaches
# the model — Claude Code treats
# SessionStart stdout as context)
# - PreToolUse fires /agentmemory/enrich
# on every file-touching tool call
# (resource cleanup, not a token
# fix — PreToolUse stdout is debug
# log only per Claude Code docs)
# Observations are still captured via
# PostToolUse regardless of this flag.
# GRAPH_EXTRACTION_ENABLED=false
# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
# model to skip its hidden thinking pass
# during graph extraction. Faster runs;
# relation quality can drop slightly.
# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
# LESSON_DECAY_ENABLED=true
# OBSIDIAN_AUTO_EXPORT=false
# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
# CLAUDE_MEMORY_BRIDGE=false
# SNAPSHOT_ENABLED=false
# Storage and durability
# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
# A hard kill loses at most this window.
# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
# shutdown and deletes still save at once.
# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
# provenance; false skips it
# Sessions
# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
# the threshold as abandoned. Deletes nothing;
# new activity makes the session active again.
# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
# Capture filters (hooks)
# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
# when set, only these tools are captured
# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
# defaults: memory_*, toolsearch,
# listmcpresources, fetchmcpresource
# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
# Audit log
# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
# rows (debugging only)
# Team
# TEAM_ID=
# USER_ID=
# TEAM_MODE=private
# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
# AGENTMEMORY_TOOLS=core
```
---
`3111` portunda 138 endpoint. REST API, varsayılan olarak `127.0.0.1`'e bağlanır. Korumalı endpoint'ler `Authorization: Bearer ` gerektirir ve mesh sync endpoint'leri her iki peer'da da açıkça ayarlanmış bir `AGENTMEMORY_SECRET` gerektirir.
**Authentication varsayılan olarak açıktır.** `AGENTMEMORY_SECRET` ayarlanmadığında (shell'de veya `~/.agentmemory/.env` içinde), sunucu ilk başlatmada rastgele bir secret üretir ve onu `0600` mod ile `~/.agentmemory/secret`'a saklar. Yerel bir sunucuyla konuştuğunda paketlenmiş her istemci bunu oradan okur: CLI, görüntüleyici, `plugin/scripts` altındaki hook'lar, MCP sunucusu ve `@agentmemory/mcp` shim'i, `agentmemory connect` tarafından yazılan config'ler ve paketlenmiş OpenCode, Pi, OpenClaw, Hermes ve filesystem-watcher entegrasyonları. Saklanan secret, yalnızca loopback URL'lerine (`localhost`, `127.0.0.0/8`, `::1`) gönderilir. Açık bir `AGENTMEMORY_SECRET` her zaman kazanır ve uzak istemcilerin de bunu ayarlamış olması gerekir. Docker ve `deploy/` entrypoint'leri zaten kendi secret'larını üretir ve export eder. API'yi elle çağırmak için:
```bash
curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" 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: [`src/triggers/api.ts`](../src/triggers/api.ts)
**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, `/capture-spool/-.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).** Her bilgi grafı düğümü ve kenarı, geldiği en yeni 32 gözlemin id'lerini tutar. Bu üst sınırdan önce yazılan depolar, hot bir düğüm başına binlerce id tutabilir, bu da graf aramasını ve görüntüleyiciyi yavaşlatır veya worker'ı düşürür. agentmemory bunu kendi başına düzeltir: yükseltmeden sonraki ilk başlatmada, her düğümü, kenarı, supersede edilmiş kenarı (temporal graf geçmişi) ve önbelleğe alınmış snapshot'ı arka planda, aralarında bir duraklama olan küçük parçalar halinde üst sınıra kırpar, bu yüzden arama, yakalama ve görüntüleyici çalışmayı sürdürür. İlerlemesini kaydeder, bir yeniden başlatmadan sonra devam eder ve tamamlandıktan sonra bir daha asla çalışmaz. `/agentmemory/status` ve görüntüleyicinin Health sayfası, bunu bekliyor (pending), çalışıyor (mevcut scope ve pozisyonla), tamamlandı veya başarısız olarak gösterir. Kapatmak için `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` ayarlayı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.
```bash
curl -X POST http://localhost:3111/agentmemory/graph/compact -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.
```bash
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
```bash
npm run dev # Hot reload
npm run build # Production build
npm test # 2,500+ tests
npm run test:integration # API tests (requires running services)
```
**Ön koşullar:** npm/npx ile Node.js >= 20; [iii-engine](https://iii.dev/docs) v0.22.1 veya Docker. macOS/Linux otomatik engine kurulumu, ayrıca `curl`, bir POSIX `sh` ve `tar` gerektirir; yerel Windows, manuel sabitlenmiş `iii.exe`, WSL2 veya Docker Desktop kullanır.
