کوڈنگ سیشنز اور ایجنٹس کے درمیان مستقل میموری۔
Claude Code، GitHub Copilot CLI، Cursor، Gemini CLI، Codex CLI، Hermes، OpenClaw، pi، Oh My Pi، DeepSeek Harness، OpenCode، اور کسی بھی MCP کلائنٹ کے لیے مستقل میموری۔
---
AgentMemory کوڈنگ سیشن ریکارڈ کرتا ہے تاکہ پرانے فیصلے اور اصلاحات تلاش کیے جا سکیں۔ مختلف ٹولز میں ایک ہی میموری اسٹور استعمال کریں، محفوظ مواد دیکھیں اور ماڈل کو دیا جانے والا سیاق منتخب کریں۔
## انسٹال
تقاضے:
- Node.js 20 یا نیا، npm اور npx کے ساتھ (`node -v`، `npm -v`، اور `npx -v`)۔
- macOS/Linux پر خودکار سیٹ اپ کے لیے `curl`، POSIX `sh` اور `tar` درکار ہیں۔
- Windows / WSL2: [Windows](#windows).
معیاری fresh-install کمانڈ:
```bash
npx -y @agentmemory/agentmemory@latest
```
ایجنٹ اور فراہم کنندہ یا بغیر کلید والا موڈ منتخب کریں۔ سیٹ اپ ترتیب محفوظ کرکے میموری سرور شروع کرتا ہے اور عالمی تنصیب کا اختیار دیتا ہے۔ `-y` npm کی تصدیق قبول کرتا ہے؛ `@latest` تازہ ترین ریلیز منتخب کرتا ہے۔ LLM کمپریشن کے لیے فراہم کنندہ اور `AGENTMEMORY_AUTO_COMPRESS=true` دونوں ضروری ہیں۔
Keyless موڈ ویکٹر embeddings کو غیر فعال کر دیتا ہے۔ `memory_recall` (جو `mem::search` راستہ استعمال کرتا ہے) BM25 استعمال کرتا ہے، جبکہ `memory_smart_search` موجودہ graph ڈیٹا ہونے کی صورت میں structural graph matches کو بھی فیوز کر سکتا ہے۔ مفت آن-ڈیوائس سیمینٹک ریکال کے لیے، `~/.agentmemory/.env` میں `EMBEDDING_PROVIDER=local` سیٹ کریں اور دوبارہ شروع کریں۔ پہلی embedding درخواست `Xenova/all-MiniLM-L6-v2` ڈاؤن لوڈ کرتی ہے؛ اس ابتدائی ماڈل ڈاؤن لوڈ کے بعد inference مقامی طور پر چلتا ہے۔
API کا پتہ `http://localhost:3111` اور براہ راست ویوئر کا `http://localhost:3113` ہے۔ دونوں بطور طے شدہ loopback استعمال کرتے ہیں۔ ترتیب `~/.agentmemory/.env` میں ہوتی ہے۔ [ڈیٹا اسٹوریج](#data-storage).
پھر ثابت کریں کہ ریکال کام کر رہا ہے اور اپنے ایجنٹ کو اس کی اسکلز دیں:
```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
```
کی-ورڈ سرچز کو ڈیفالٹ keyless موڈ میں BM25 کے ذریعے ہِٹ ہونا چاہیے۔ ڈیمو کی `database performance optimization` کوئری جانستہ طور پر سیمینٹک ہے اور جب تک کوئی embedding پرووائیڈر کنفیگر نہ ہو، صفر نتائج دے سکتی ہے۔
کسی کوڈنگ ایجنٹ سے یہ سارا کام کروانا چاہتے ہیں؟ اسے صرف ایک ہدایت دیں:
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
`agentmemory connect ` سے مزید ایجنٹ جوڑیں۔ [معاون انضمام](#works-with-every-agent) اور [روزمرہ کمانڈز](#everyday-commands) دیکھیں۔
Global install / EACCES
```bash
npm install -g @agentmemory/agentmemory@latest
```
اوپر دی گئی npx کمانڈ معیاری fresh-install راستہ ہی رہتی ہے اور global-prefix پرمیشن مسائل سے بچاتی ہے۔
npx پرانا ورژن دیتا ہے
npx ہر ورژن کو علیحدہ طور پر کیش کرتا ہے۔ `npx -y @agentmemory/agentmemory@latest` سے تازہ ترین ورژن پر مجبور کریں، یا ایک بار `rm -rf ~/.npm/_npx` سے کیش صاف کریں (macOS/Linux؛ Windows پر `%LOCALAPPDATA%\npm-cache\_npx` ڈیلیٹ کریں)۔
---
agentmemory کسی بھی ایسے ایجنٹ کے ساتھ کام کرتا ہے جو hooks، MCP، یا REST API کو سپورٹ کرتا ہو۔ تمام ایجنٹس ایک ہی میموری سرور کا اشتراک کرتے ہیں۔
Claude Code نیٹیو پلگ ان + 12 ہکس + MCP
Codex CLI نیٹیو پلگ ان + 6 ہکس + MCP
GitHub Copilot CLI MCP + پلگ ان ہکس/اسکلز
Cursor مقامی پلگ ان + lifecycle hooks + MCP
OpenCode کیپچر پلگ ان + MCP
Devin 6 ہکس + اسکلز + MCP
OpenClaw نیٹیو پلگ ان + MCP
Hermes نیٹیو پلگ ان + MCP
pi مقامی recall + capture + skills
OpenHuman نیٹیو Memory trait بیک اینڈ
Gemini CLI MCP سرور
Antigravity MCP + ہکس
Claude Desktop MCP سرور
Warp کنکٹ + MCP + اسکلز
Zed MCP سرور
Cline MCP سرور
Continue MCP سرور
Droid MCP سرور
Kiro MCP سرور
Qwen Code MCP سرور
DeepSeek Harness مقامی capture + MCP
Roo Code MCP سرور
Kilo Code MCP سرور
Goose MCP سرور
Aider REST API
Oh My Pi مقامی recall + capture + skills + اختیاری MCP
MCP یا HTTP بولنے والے کسی بھی ایجنٹ کے ساتھ کام کرتا ہے۔ ایک سرور، میموریز ان سب کے درمیان مشترک ہیں۔
---
### ڈیٹا اسٹوریج
میموری بطور طے شدہ ریپوزٹری کے باہر محفوظ ہوتی ہے۔ انسٹینس 0 موجودہ `./data/state_store.db` دوبارہ استعمال کرتا ہے۔ `--data-dir ` یا `AGENTMEMORY_DATA_DIR` سے جگہ منتخب کریں اور دوبارہ آغاز یا اپ گریڈ میں وہی ڈائریکٹری رکھیں۔
| پلیٹ فارم | ڈیٹا ڈائریکٹری |
|---|---|
| macOS | `~/Library/Application Support/agentmemory` |
| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
| Windows | `%APPDATA%\agentmemory` |
```bash
agentmemory --data-dir ~/.agentmemory-projects/main
agentmemory --instance 1
```
`--instance 1` ذیلی ڈائریکٹری `instance-1`، API پورٹ `3211` اور ویوئر پورٹ `3213` استعمال کرتا ہے۔ Redis اور بیک اینڈ منتقلی کے لیے [اسٹوریج اور بیک اپ](../docs/reliability/state-storage.md) دیکھیں۔
تازہ ترین ریلیز نوٹس: [CHANGELOG.md](../CHANGELOG.md)۔
---
موجودہ بازیافت کے نتائج، پیمانوں کی تعریفیں اور دوبارہ جانچ کے مراحل:
[0.9.31 · 2026-10-28 · strict recall-all@5](../docs/benchmarks/2026-10-28-retrieval-evaluation.md) · [eval/README.md](../eval/README.md).
---
مصنوعات اور تنصیب کے طریقوں کا تازہ موازنہ، حوالوں کے ساتھ:
[AgentMemory / Mem0 / Supermemory / Zep / Letta / Cognee / claude-mem](../benchmark/COMPARISON.md) · 2026-10-28.
---
### 30 سیکنڈ میں آزمائیں
```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 حقیقت پسندانہ سیشنز (JWT auth، N+1 query fix، rate limiting) seed کرتا ہے اور ان کے خلاف سرچز چلاتا ہے۔ Keyless انسٹالز ویکٹرز کو غیر فعال کر دیتے ہیں، لہٰذا `mem::search` کی-ورڈ کوئریز کو BM25 کے ذریعے ہِٹ ہونا چاہیے جبکہ `database performance optimization` صفر نتائج دے سکتی ہے۔ `smart-search` گراف ڈیٹا موجود ہونے کی صورت میں اضافی طور پر structural graph matches بھی واپس کر سکتا ہے۔ سیمینٹک کوئری کو ویکٹرز کے ذریعے N+1 fix ڈھونڈنے کے قابل بنانے کے لیے، `EMBEDDING_PROVIDER=local` سیٹ کریں، دوبارہ شروع کریں، اور پہلے ماڈل ڈاؤن لوڈ کو مکمل ہونے دیں۔
میموری کو لائیو بنتے دیکھنے کے لیے `http://localhost:3113` کھولیں۔
### ایک تازہ انسٹال اور ریسٹارٹ persistence کی توثیق کریں
سرور چلتے ہوئے صحت، ویوئر اور حالت کی جانچ کریں۔
```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
```
`status` سرور کی صحت، فراہم کنندہ، embedding mode، capture delivery اور بحالی دکھاتا ہے۔ محفوظ REST درخواست میں سرور کا راز درکار ہے۔ مقررہ `AGENTMEMORY_SECRET` استعمال کریں؛ ورنہ بنایا گیا مقامی راز پڑھیں۔
```bash
# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
-H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
-H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
پھر `npx -y @agentmemory/agentmemory@latest stop` چلائیں، Terminal 1 میں معیاری کمانڈ دوبارہ شروع کریں، `/agentmemory/livez` کا انتظار کریں، اور سرچ دہرائیں۔ probe اب بھی واپس آنا چاہیے۔ اگر آپ نے کسٹم `--data-dir` منتخب کیا تھا، تو ریسٹارٹ پر وہی ڈائرکٹری پاس کریں۔
### روزمرہ کی کمانڈز
انسٹال اور سیٹ اپ اوپر [انسٹال](#install) میں موجود ہیں (پہلی بار چلانے پر آپ کی رہنمائی ہوتی ہے)۔ روزمرہ:
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
agentmemory status # health, providers and recovery state
agentmemory capture # inspect capture inbox and offline spool
agentmemory capture --drain # replay queued observations
agentmemory connect # connect another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
```
### سیشن ری پلے
agentmemory جو بھی سیشن ریکارڈ کرتا ہے وہ دوبارہ چلایا (replay) جا سکتا ہے۔ ویور کھولیں، **Replay** ٹیب منتخب کریں، اور ٹائم لائن میں آگے پیچھے دیکھیں: prompts، tool calls، tool results، اور responses الگ الگ events کی صورت میں play/pause، رفتار کنٹرول (0.5x سے 4x)، اور کی بورڈ شارٹ کٹس (toggle کے لیے space، قدم بڑھانے کے لیے arrows) کے ساتھ دکھائے جاتے ہیں۔
پرانے Claude Code JSONL transcripts لانے کے لیے:
```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
```
درآمد شدہ سیشن Replay میں مقامی سیشن کے ساتھ نظر آتے ہیں، تلاش کے لیے انڈیکس ہوتے ہیں اور origin channel `import` پاتے ہیں۔ سیشن کی پروسیسنگ سے crystals اور lessons بھی بن سکتے ہیں۔
> **خبردار اگر آپ `import-jsonl` کو اپنے بنیادی کیپچر راستے کے طور پر استعمال کر رہے ہیں:** Claude Code کی `cleanupPeriodDays` سیٹنگ (`~/.claude/settings.json` میں، ڈیفالٹ **30**) اس حد سے پرانے JSONL transcripts کو `~/.claude/projects/` سے خودکار طور پر ڈیلیٹ کر دیتی ہے۔ اگر آپ مہینوں پرانی Claude Code ہسٹری پر agentmemory کو تازہ انسٹال کرتے ہیں، تو 30 دن سے پرانی کوئی بھی چیز پہلے import سے پہلے ہی ختم ہو چکی ہوگی۔ یا تو `import-jsonl` کو cron پر چلائیں، `cleanupPeriodDays` کو زیادہ بڑھا دیں، یا auto-capture hooks جوڑیں (ڈیفالٹ plugin انسٹال راستہ) تاکہ سیشن کے لائیو ہونے کے دوران ہی ہر turn agentmemory میں پہنچ جائے اور JSONL cleanup غیر اہم ہو جائے۔
### اپ گریڈ / مینٹیننس
جب آپ جانستہ طور پر اپنا مقامی رن ٹائم اپ ڈیٹ کرنا چاہیں تو maintenance کمانڈ استعمال کریں:
```bash
npx -y @agentmemory/agentmemory@latest upgrade
```
یہ مقامی رن ٹائم اپ ڈیٹ کرتا ہے اور موجودہ ورکنگ ڈائریکٹری کی JavaScript dependencies بھی بدل سکتا ہے۔ ڈیٹا کا بیک اپ لیں اور موجودہ تنصیب اپ ڈیٹ کرنے سے پہلے [اپ گریڈ گائیڈ](../docs/upgrades/iii-0.25.md) پڑھیں۔
### Claude Code (ایک بلاک، اسے پیسٹ کریں)
```text
Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code بغیر plugin انسٹال کے (MCP-standalone راستہ)
اگر آپ `/plugin install` استعمال کرنے کے بجائے agentmemory کے MCP سرور کو براہِ راست `~/.claude.json` (پہلے سے طے شدہ راستہ) کے ذریعے جوڑتے ہیں، تو Claude Code کبھی `${CLAUDE_PLUGIN_ROOT}` کو resolve نہیں کرتا اور آپ کو hook اسکرپٹس کو `~/.claude/settings.json` (پہلے سے طے شدہ راستہ) میں absolute paths کی طرف پوائنٹ کرنا پڑتا ہے۔ یہ paths عام طور پر agentmemory کا ورژن شامل رکھتے ہیں (مثلاً `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`)، لہٰذا اگلا اپ گریڈ خاموشی سے ہر ہک کو توڑ دیتا ہے۔
متبادل حل:
```bash
agentmemory connect claude-code --with-hooks
```
یہ کمانڈ MCP سرور کو کنفیگر کرتی ہے اور ساتھ آنے والے hooks کو Claude Code کی صارف کنفیگریشن میں ضم کرتی ہے۔ اگر `CLAUDE_CONFIG_DIR` سیٹ نہیں ہے، خالی ہے یا اس میں صرف وائٹ اسپیس ہے تو یہ MCP کے لیے `~/.claude.json` اور hooks کے لیے `~/.claude/settings.json` استعمال کرتی ہے۔ ڈائرکٹری کی دیگر قدریں بالکل اسی طرح استعمال ہوتی ہیں جیسے دی گئی ہوں، بشمول شروع اور آخر کی وائٹ اسپیس۔ اپنی مرضی کی ڈائرکٹری کے لیے اس کمانڈ اور Claude Code دونوں کے لیے `CLAUDE_CONFIG_DIR` کی ایک ہی غیر خالی قدر سیٹ کریں؛ تب فائلیں بالترتیب `$CLAUDE_CONFIG_DIR/.claude.json` اور `$CLAUDE_CONFIG_DIR/settings.json` ہوں گی۔ Claude Code کو یہ قدر اپنے لانچ ماحول میں ملنی چاہیے، چاہے کنیکٹر اسے AgentMemory کی `.env` سے پڑھتا ہو۔ اس کمانڈ کو چلانے سے پہلے اپنی مرضی کی ڈائرکٹری بنائیں؛ ورنہ کنیکٹر Claude Code کو شناخت نہ ہونے کی وجہ سے چھوڑ دے گا۔ اگر shell کی قدر میں صرف وائٹ اسپیس ہو تو Claude Code شروع کرنے سے پہلے ماحول سے `CLAUDE_CONFIG_DIR` ہٹا دیں تاکہ وہ بھی پہلے سے طے شدہ پروفائل استعمال کرے۔ مطلق راستہ استعمال کریں۔ نسبتی راستے کام کی ڈائریکٹری کے لحاظ سے متعین ہوتے ہیں، اس لیے دونوں کمانڈز ایک ہی ڈائریکٹری سے چلائیں۔
Hook کمانڈز انسٹال شدہ پیکیج کے ساتھ آنے والی `plugin/` ڈائرکٹری کے مطلق راستے استعمال کرتی ہیں۔ agentmemory اپ گریڈ کرنے کے بعد ان راستوں کو تازہ کرنے کے لیے کمانڈ دوبارہ چلائیں۔ کنفیگریشن فائلوں میں صارف کی entries محفوظ رہتی ہیں؛ صرف agentmemory کی پچھلی entries تبدیل ہوتی ہیں۔ `/plugin install` کا استعمال ہی تجویز کردہ طریقہ رہتا ہے۔
ریموٹ یا محفوظ deployments کے لیے، Claude Code کو `AGENTMEMORY_URL` اور `AGENTMEMORY_SECRET` سیٹ کر کے لانچ کریں۔ plugin دونوں قدریں اپنے bundled MCP سرور تک پہنچاتا ہے؛ جب `AGENTMEMORY_URL` خالی ہو، تو MCP shim `http://localhost:3111` استعمال کرتا ہے۔
### Codex CLI (Codex plugin پلیٹ فارم)
```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 plugin اسی `plugin/` ڈائرکٹری سے شپ ہوتا ہے جس سے Claude Code plugin ہوتا ہے۔ یہ رجسٹر کرتا ہے:
- چلتے ہوئے daemon کی طرف ایک bundled stdio MCP bridge، بغیر npm download یا fallback store کے۔ ایک unreleased build ٹیسٹ کرنے کے لیے [مقامی Codex guide](../docs/plugins/codex-local.md) دیکھیں۔
- 6 lifecycle ہکس: `SessionStart`، `UserPromptSubmit`، `PreToolUse`، `PostToolUse`، `PreCompact`، `Stop`
- 9 invocable اسکلز: `/recall`، `/remember`، `/session-history`، `/forget`، `/recap`، `/handoff`، `/lesson`، `/commit-context`، `/commit-history`، نیز 8 reference اسکلز جنہیں ایجنٹ ضرورت پڑنے پر لوڈ کرتا ہے (memory discipline، MCP tools، REST API، config، agents، hooks، architecture، اور skill-authoring گائیڈ)
Codex کا hook انجن `CLAUDE_PLUGIN_ROOT` کو hook subprocesses میں انجیکٹ کرتا ہے ([`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs) کے مطابق)، لہٰذا وہی hook اسکرپٹس دونوں hosts پر بغیر دہرائے کام کرتے ہیں۔ Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure events صرف Claude-Code کے لیے ہیں اور Codex کے لیے رجسٹر نہیں ہوتے۔
#### Codex hooks پر اعتماد اور مطابقت
Codex CLI 0.150.1 کے ساتھ native plugin hook dispatch تصدیق شدہ ہے۔ کیپچر کی توقع کرنے سے پہلے plugin hooks پر اعتماد کریں۔ Desktop کا رویہ اس کے bundled runtime پر منحصر ہے؛ کوئی workaround فعال کرنے سے پہلے `/hooks` چیک کریں اور ایک captured event کی تصدیق کریں۔
اگر آپ کا host global hooks کا تقاضا کرتا ہے، تو کمانڈز کو `~/.codex/hooks.json` میں mirror کریں۔ جب MCP پہلے سے wired ہو، تو موجودہ connector کو hook installation تک پہنچنے کے لیے `--force` کی ضرورت ہوتی ہے:
```bash
agentmemory connect codex --with-hooks --force
```
یہ global hooks کو ضم کرتا ہے اور agentmemory MCP entry کو دوبارہ لکھتا ہے، غیر متعلقہ entries کو محفوظ رکھتے ہوئے۔ `--force` استعمال کرنے سے پہلے کسی بھی کسٹم agentmemory endpoint سیٹنگز کا جائزہ لیں۔ script paths ریفریش کرنے کے لیے اپ گریڈ کے بعد دوبارہ چلائیں۔ duplicate capture سے بچنے کے لیے native plugin hooks یا global کاپیز میں سے کوئی ایک فعال کریں۔
### GitHub Copilot CLI
VS Code کے agent mode کے لیے، [Copilot MCP اور automatic-capture گائیڈ](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions) استعمال کریں۔ CLI connector VS Code کو کنفیگر نہیں کرتا۔
```bash
# MCP-only wiring
agentmemory connect copilot-cli
# Alternatively, full hooks/skills plugin from the GitHub subdir
copilot plugin install rohitg00/agentmemory:plugin
```
`agentmemory connect copilot-cli` `mcpServers.agentmemory` کو `~/.copilot/mcp-config.json` میں ضم کرتا ہے (یا جب `COPILOT_HOME` سیٹ ہو تو `$COPILOT_HOME/mcp-config.json` میں) اور موجودہ سرورز کو محفوظ رکھتا ہے۔ نیٹیو Windows پر یہ واحد خودکار `connect` adapter ہے؛ ہر دوسرے نیٹیو Windows ایجنٹ کو دستی طور پر کنفیگر کریں۔ WSL `connect` صرف اس وقت معاون ہے جب target ایجنٹ اسی WSL ماحول میں انسٹال ہو۔ Copilot اگلے لانچ پر یا `/mcp` کے بعد MCP سرور اٹھا لیتا ہے۔ مکمل hook/skill تجربے کے لیے plugin بھی انسٹال کریں۔
### Cursor
`agentmemory connect cursor` سے MCP ترتیب دیں۔ **Settings → Plugins → Add marketplace** میں `.cursor-plugin/plugin.json` والا checkout منتخب کریں، agentmemory فعال کریں اور reload کریں۔ پلگ ان lifecycle capture، workspace شناخت، skills اور MCP دیتا ہے۔ دوہری capture سے بچنے کے لیے پلگ ان hooks یا `~/.cursor/hooks.json` کے دستی hooks میں سے ایک ہی استعمال کریں۔
[Cursor](../integrations/cursor/)
### Pi / Oh My Pi / DeepSeek Harness
```bash
agentmemory connect pi --with-mcp
agentmemory connect omp --with-mcp
agentmemory connect dsh --with-hooks
```
اپنے ہوسٹ کی کمانڈ منتخب کریں۔ Pi اور OMP مقامی recall/capture، آف لائن replay اور 17 skills نصب کرتے ہیں؛ `--with-mcp` مکمل ٹول سیٹ شامل کرتا ہے۔ Pi میں `/reload` چلائیں یا OMP دوبارہ شروع کریں، پھر `/agentmemory-status` دیکھیں۔ DSH، MCP اور ساتھ آنے والا capture plugin نصب کرتا ہے؛ جوڑنے کے بعد دوبارہ شروع کریں۔
Pi کے لیے قابل تنصیب `@agentmemory/pi` پیکیج بھی ہے۔ مقامی تنصیب اور npm کی دستیابی کے لیے [Pi گائیڈ](../integrations/pi/) دیکھیں۔ ہر ہوسٹ پر ایک ہی طریقہ استعمال کریں۔
[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
OpenClaw (یہ prompt پیسٹ کریں)
```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`.
```
مکمل گائیڈ: [`integrations/openclaw/`](../integrations/openclaw/)
Hermes Agent (یہ prompt پیسٹ کریں)
```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 https://github.com/rohitg00/agentmemory to ~/.hermes/plugins/agentmemory.
```
مکمل گائیڈ: [`integrations/hermes/`](../integrations/hermes/)
### دیگر ایجنٹس
میموری سرور شروع کریں: `npx -y @agentmemory/agentmemory@latest`
#### `npx skills add` کے ذریعے نیٹیو اسکلز
agentmemory 17 اسکلز کو Claude-Code طرز کے `/SKILL.md` فارمیٹ میں شپ کرتا ہے: 9 invocable ایکشن اسکلز (`remember`، `recall`، `recap`، `handoff`، `forget`، `lesson`، `commit-context`، `commit-history`، `session-history`) اور 8 reference اسکلز جنہیں ایجنٹ ضرورت پڑنے پر لوڈ کرتا ہے (`memory-discipline`، `agentmemory-mcp-tools`، `agentmemory-rest-api`، `agentmemory-config`، `agentmemory-agents`، `agentmemory-hooks`، `agentmemory-architecture`، `write-agentmemory-skill`)۔ reference اسکلز سورس سے تیار کردہ data tables رکھتی ہیں، لہٰذا یہ کبھی drift نہیں کرتیں۔ vercel-labs کا [`skills`](https://npmjs.com/package/skills) CLI انہیں calling ایجنٹ کی نیٹیو اسکل ڈائرکٹری میں 50+ ایجنٹس (Claude Code، Cursor، Cline، Continue، Droid، Warp، Codex، Antigravity، Kiro، OpenCode، Goose، Roo، Trae، Windsurf، اور مزید) میں خودکار طور پر انسٹال کرتا ہے:
```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
```
یہ `agentmemory connect ` کا **تکمیلی (complementary)** ہے:
Hermes، OpenClaw، Pi اور Oh My Pi connectors بطور طے شدہ مقامی انضمام اور skills نصب کرتے ہیں؛ MCP کو `--with-mcp` سے شامل کریں۔ دوسرے ہوسٹس پر `npx skills add rohitg00/agentmemory` سے skills نصب کریں۔
ان چند ایجنٹس کے لیے جنہیں skills CLI ابھی کَوَر نہیں کرتا (Zed v1.3.x اور اس سے نیچے)، خود 17 SKILL.md فائلیں ایجنٹ کی نیٹیو اسکل ڈائرکٹری میں رکھیں؛ وہی فارمیٹ ہر جگہ کام کرتا ہے۔
#### معیاری MCP بلاک
agentmemory کا entry ہر اس host پر **ایک ہی MCP سرور بلاک** ہے جو `mcpServers` شکل استعمال کرتا ہے (Cursor، Claude Desktop، Cline، Roo Code، Gemini CLI، OpenClaw):
```json
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"],
"env": {
"AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
"AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
}
}
```
**اس entry کو host کی config فائل میں موجودہ `mcpServers` object میں ضم کریں**؛ فائل کو تبدیل نہ کریں۔ اگر فائل میں پہلے سے دوسرے سرورز موجود ہیں، تو `agentmemory` کو ان کے ساتھ `mcpServers` کے اندر ایک اور key کے طور پر شامل کریں۔ اگر `mcpServers` مکمل طور پر غائب ہے، تو بلاک کو `{ "mcpServers": { ... } }` کے اندر پیسٹ کریں۔ `${VAR}` placeholders MCP-سرور لانچ کے وقت shell سے `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` وراثت میں لیتے ہیں؛ سیٹ نہ ہونے والی vars خالی strings پاس کرتی ہیں اور shim `http://localhost:3111` پر فال بیک کرتا ہے۔ ایک جوڑا گیا entry مقامی اور ریموٹ (k8s / reverse-proxied) دونوں deployments کو کَوَر کرتا ہے۔
| ایجنٹ | کنفیگ فائل | نوٹس |
|---|---|---|
| **Cursor (صرف MCP)** | `~/.cursor/mcp.json` | `mcpServers` میں ضم کریں، یا `agentmemory connect cursor`۔ ویب سائٹ پر ون-کلک deeplink بھی دستیاب ہے۔ |
| **Cursor (مکمل plugin)** | `.cursor-plugin/` | Cursor Marketplace یا Settings → Plugins → مقامی checkout سے نصب کریں۔ مختصر adapter مشترکہ `plugin/scripts/*.mjs` چلا کر lifecycle hooks رجسٹر کرتا ہے اور skills و MCP فراہم کرتا ہے۔ یہ Cursor کی نامکمل اطلاع سے workspace شناخت کرتا ہے۔ [Cursor](#cursor) دیکھیں۔ Cursor IDE اور `cursor-agent` CLI میں کام کرتا ہے۔ |
| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | `mcpServers` میں ضم کریں۔ ترمیم کے بعد Claude Desktop کو ریسٹارٹ کریں۔ |
| **Cline / Roo Code / Kilo Code** | Cline MCP settings (Settings UI → MCP Servers → Edit) | وہی `mcpServers` بلاک۔ |
| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` MCP entry کو ضم کرتا ہے؛ `--with-hooks` Devin کے lowercase tool matchers کے ساتھ چھ نیٹیو auto-capture ہکس شامل کرتا ہے (SessionStart، UserPromptSubmit، PreToolUse، PostToolUse، Stop، SessionEnd)۔ `devin mcp list` اور devin کے اندر `/hooks` سے توثیق کریں۔ |
| **Devin CLI (مکمل plugin)** | `plugin/.devin-plugin/` | ایک checkout سے `devin plugins install ./plugin` تمام 17 اسکلز کو `/agentmemory:` سلیش کمانڈز کے طور پر رجسٹر کرتا ہے نیز MCP سرور بھی۔ Devin plugin hooks `SessionStart`/`SessionEnd` فائر نہیں کر سکتے، لہٰذا مکمل سیشن کیپچر کے لیے اسے `connect devin --with-hooks` کے ساتھ جوڑیں۔ |
| **Devin (کلاؤڈ)** | Settings → Connections → MCP servers | ایک کسٹم MCP (STDIO) شامل کریں: command `npx`، args `-y @agentmemory/mcp@latest`، env `AGENTMEMORY_URL` جو کسی نیٹ ورک پر قابلِ رسائی agentmemory deployment کی طرف اشارہ کرے نیز `AGENTMEMORY_SECRET` (کلاؤڈ سیشنز localhost تک نہیں پہنچ سکتے — [`../deploy/`](../deploy/) دیکھیں)۔ secret کو Devin Secrets میں محفوظ کریں، پھر یہ تصدیق کرنے کے لیے کہ تمام 54 ٹولز ظاہر ہو رہے ہیں "Test listing tools" استعمال کریں۔ |
| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (خودکار طور پر ضم ہو جاتا ہے)۔ |
| **GitHub Copilot CLI (صرف MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` `mcpServers.agentmemory` کو ضم کرتا ہے؛ Copilot اسے اگلے لانچ پر یا `/mcp` کے بعد اٹھا لیتا ہے۔ |
| **GitHub Copilot CLI (مکمل plugin)** | Copilot plugin install | GitHub subdir سے plugin کے لیے `copilot plugin install rohitg00/agentmemory:plugin`۔ |
| **OpenClaw** | OpenClaw MCP config | وہی `mcpServers` بلاک۔ گہرائی میں: `openclaw plugins install ./integrations/openclaw` OpenClaw کے memory slot پر قابض ہوتا ہے (`memory-core` سے خودکار سوئچ)؛ `plugins.entries.agentmemory.hooks.allowConversationAccess=true` سیٹ کریں ورنہ turn کیپچر خاموشی سے بلاک ہو جاتا ہے۔ [`integrations/openclaw`](../integrations/openclaw/) دیکھیں۔ |
| **Codex CLI (صرف MCP)** | `.codex/config.toml` | TOML شکل: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`، یا دستی طور پر `[mcp_servers.agentmemory]` شامل کریں۔ |
| **Codex CLI (مکمل plugin)** | Codex plugin marketplace | پہلے `codex plugin marketplace add rohitg00/agentmemory` پھر `codex plugin add agentmemory@agentmemory`۔ MCP + 6 lifecycle ہکس + 17 اسکلز رجسٹر کرتا ہے۔ اپنے host میں hooks پر اعتماد کریں اور کیپچر کی تصدیق کریں؛ دیکھیں [Codex سیٹ اپ اور توثیق](../docs/plugins/codex-local.md)۔ |
| **OpenCode (صرف MCP)** | `opencode.json` | مختلف شکل: top-level `mcp` key، command ایک array کے طور پر: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`۔ |
| **OpenCode (مکمل plugin)** | `plugin/opencode/` | 22 auto-capture hooks جو session lifecycle، messages، tools، errors کو کَوَر کرتے ہیں۔ Project attribution فی-سیشن ہے، لہٰذا کئی repositories پر پھیلا ہوا ایک OpenCode process ہر سیشن کو اس کے اپنے project کے تحت فائل کرتا ہے۔ دو سلیش کمانڈز (`/recall`، `/remember`)۔ `plugin/opencode/` کو اپنے OpenCode workspace میں کاپی کریں اور `opencode.json` میں plugin entry شامل کریں۔ مکمل hook ٹیبل + gap analysis کے لیے [`plugin/opencode/README.md`](../plugin/opencode/README.md) دیکھیں۔ |
| **pi** | `~/.pi/agent` | `agentmemory connect pi --with-mcp` · مقامی recall + capture + skills. [Pi](../integrations/pi/) |
| **Oh My Pi (OMP)** | `~/.omp/agent/config.yml` | `agentmemory connect omp --with-mcp` · مقامی recall + capture + skills. [Oh My Pi](../integrations/omp/) |
| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` 6-hook میموری provider دیتا ہے (prefetch، turn کیپچر، session end، pre-compress، MEMORY.md mirroring، system prompt block)۔ `hermes plugins doctor` اور `hermes memory status` سے توثیق کریں۔ [`integrations/hermes`](../integrations/hermes/) دیکھیں۔ |
| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` معیاری `mcpServers` بلاک لکھتا ہے۔ Hook payload Claude Code کے ساتھ field-compatible ہے، لہٰذا موجودہ 12-hook اسکرپٹس بغیر ترمیم کے کام کرتے ہیں؛ انہیں اسی `settings.json` میں `hooks` سیکشن کے ذریعے جوڑیں۔ |
| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` مشترکہ customization ڈائرکٹری میں MCP اور capture hooks انسٹال کرتا ہے۔ دیکھیں [Antigravity سیٹ اپ اور حدود](../docs/plugins/antigravity.md)۔ |
| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` موجودہ IDE ورژنز جیسی ہی MCP اور hook configuration استعمال کرتا ہے۔ موجودہ انسٹالیشنز کو `--force` کے ساتھ ریفریش کرنا چاہیے؛ دیکھیں [اپ گریڈ نوٹس](../docs/plugins/antigravity.md)۔ |
| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` user-level کنفیگ لکھتا ہے۔ Workspace overrides آپ کے کوڈ کے ساتھ `.kiro/settings/mcp.json` میں جاتے ہیں۔ |
| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` معیاری `mcpServers` بلاک لکھتا ہے۔ Warp `.claude/skills/` سے اسکلز کو بھی خودکار طور پر دریافت کرتا ہے؛ ایک بار Claude Code plugin انسٹال ہونے پر 9 agentmemory اسکلز (`remember`، `recall`، `recap`، `handoff`، `forget`، `lesson`، `commit-context`، `commit-history`، `session-history`) Warp کے slash-command palette میں نیٹیو طور پر ظاہر ہوتی ہیں۔ |
| **Cline (CLI)** | `~/.cline/data/settings/cline_mcp_settings.json` | `agentmemory connect cline` معیاری `mcpServers` بلاک لکھتا ہے۔ VS Code extension صارفین: وہی بلاک Cline Settings → MCP Servers → Edit JSON کے ذریعے پیسٹ کریں۔ |
| **Continue.dev** | `~/.continue/config.yaml` (ترجیحی) یا `config.json` (legacy) | `agentmemory connect continue` ترتیب نہ ہونے پر `config.yaml` بناتا ہے یا موجودہ `config.json` اپ ڈیٹ کرتا ہے۔ موجودہ YAML کے comments اور anchors محفوظ رکھنے کے لیے اسے تبدیل نہیں کرتا، بلکہ `mcpServers:` کے نیچے چسپاں کرنے کا بلاک دکھاتا ہے۔ Continue کا `mcpServers` ایک array ہے۔ |
| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` `context_servers` کے تحت لکھتا ہے (Zed کی اپنی key، `mcpServers` نہیں)۔ ریموٹ MCP سرورز کو بجائے `{"url": "..."}` کے ذریعے جوڑا جا سکتا ہے۔ |
| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` معیاری `mcpServers` بلاک لکھتا ہے۔ Project-scoped overrides `/.factory/mcp.json` میں جاتے ہیں۔ نیٹیو auto-capture کے لیے `--with-hooks` پاس کریں۔ |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` سے MCP ٹول فعال ہوتے ہیں۔ AgentMemory میں شامل مقامی کیپچر پلگ ان لوڈ کرنے کے لیے `--with-hooks` شامل کریں۔ الگ پلگ ان پیکیج کی ضرورت نہیں ہے۔ [DSH](../docs/dsh.md). |
| **Goose** | Goose MCP settings UI | وہی `mcpServers` بلاک؛ `goose configure` → Add Extension → MCP استعمال کریں۔ `~/.config/goose/config.yaml` پر براہِ راست YAML ترمیم معاون ہے لیکن schema `extensions:` + `cmd` استعمال کرتا ہے (`mcpServers:` + `command` نہیں)۔ |
| **Aider** | n/a | [REST API](#validate-a-fresh-install-and-restart-persistence) |
| **معاونت یافتہ ایجنٹس** | صرف skills | `npx skills add rohitg00/agentmemory`; انسٹال کرنے کے لیے skills اور مطلوبہ ایجنٹس منتخب کریں۔ |
**Sandboxed MCP کلائنٹس** (Flatpak / Snap / restrictive containers) جو host کے `localhost` تک نہیں پہنچ سکتے: `env` بلاک میں `"AGENTMEMORY_FORCE_PROXY": "1"` بھی سیٹ کریں، اور `AGENTMEMORY_URL` کو کسی ایسے route کی طرف پوائنٹ کریں جہاں sandbox واقعی پہنچ سکے (مثلاً آپ کا LAN IP)۔
### پروگرامیٹک رسائی
کسی بھی زبان سے [REST API](#api) یا ایجنٹ سے [MCP ٹولز](#mcp-server) استعمال کریں۔ REST میں JSON اور Bearer توثیق درکار ہے؛ [محفوظ کرنے اور تلاش کی مثال](#validate-a-fresh-install-and-restart-persistence) دیکھیں۔ رن ٹائم سے براہ راست انضمام کے لیے [Python مثالیں](../examples/python/) موجود ہیں۔
### سورس سے
```bash
git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start
```
`npm start` نصب شدہ CLI والا ہی مقامی سرور شروع کرتا ہے۔ ضروریات [تنصیب](#install) میں ہیں؛ API اور ویوئر `127.0.0.1` استعمال کرتے ہیں۔
### Windows
agentmemory Windows 10/11 پر چلتا ہے؛ WSL2 Linux طریقے سے engine خود انسٹال کر سکتا ہے۔ Native Windows پر iii-engine v0.25.1 binary دستی طور پر انسٹال کریں: [iii v0.25.1 release page](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.1) سے archive ڈاؤن لوڈ، checksum کی تصدیق، اور `iii.exe` کو `PATH` پر رکھیں۔ CLI ZIP خود نہیں کھولتا
Native Windows پر MCP خودکار wiring صرف `agentmemory connect copilot-cli` کے لیے ہے؛ دوسرے agents کے لیے [Other agents](#other-agents) کا دستی MCP block استعمال کریں۔ WSL میں `connect` تب چلائیں جب target agent وہیں نصب ہو
**صرف standalone MCP، engine کے بغیر۔** اگر REST API، viewer یا runtime services درکار نہ ہوں:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
# or
npx -y @agentmemory/mcp
```
`agentmemory doctor` چلائیں یا `--verbose` کے ساتھ دوبارہ آغاز کریں۔ طے شدہ پورٹس مصروف ہوں تو `--port ` یا `--instance ` استعمال کریں۔ مطابقت اور بحالی کے لیے [اپ گریڈ گائیڈ](../docs/upgrades/iii-0.25.md) دیکھیں۔
---
ڈیپلائی
Docker Compose یا نیچے دیے پلیٹ فارم ٹیمپلیٹس سے خود ہوسٹ کریں۔ میموری اور اسناد `/data` والیوم میں رہتی ہیں۔ اپ گریڈ کرتے وقت بیک اپ لیں اور یہی والیوم دوبارہ استعمال کریں۔ توثیق، نیٹ ورک اور منتقلی کے لیے [ڈیپلائمنٹ گائیڈ](../deploy/README.md) دیکھیں۔
Render کے ون-کلک ڈیپلائی بٹن کو repository کی root میں `render.yaml` درکار ہے، جسے ہم جانستہ طور پر صاف رکھتے ہیں۔ in-repo blueprint کی طرف دستی طور پر اشارہ کرنے کے لیے [`../deploy/render/`](.././deploy/render/README.md) میں دستاویزی Render Blueprint فلو استعمال کریں۔
مکمل سیٹ اپ تفصیلات (HMAC کیپچر، ویور SSH tunnel، rotation، backup، cost floors) [`../deploy/`](.././deploy/README.md) میں موجود ہیں:
- [`../deploy/fly`](.././deploy/fly/README.md): `auto_stop_machines = "stop"` کے ساتھ ایک مشین؛ سب سے سستا idle۔
- [`../deploy/railway`](.././deploy/railway/README.md): Hobby plan فلیٹ فیس، dashboard میں volume۔
- [`../deploy/render`](.././deploy/render/README.md): Blueprint فلو، paid plans پر خودکار disk snapshots۔
- [`../deploy/coolify`](.././deploy/coolify/README.md): [Coolify](https://coolify.io/self-hosted) کے ذریعے آپ کے اپنے VPS پر سیلف-ہوسٹڈ؛ وہی Docker Compose اسٹیک، host اور data دونوں آپ کے اپنے۔
REST پورٹ `3111` اور ویوئر `3113` استعمال کرتے ہیں۔ انہیں نجی رکھیں یا توثیق اور TLS سے محفوظ بنائیں۔ پلیٹ فارم کی رسائی کی ترتیب اور [پرانے Docker کی منتقلی](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) ڈیپلائمنٹ گائیڈ میں ہیں۔
---
منصوبے کی معلومات گفتگو اور ہدایات کی فائلوں میں بکھر جاتی ہیں۔ AgentMemory موجودہ ایجنٹ سے پرانے فیصلے، اصلاحات اور سیکھے گئے اسباق تلاش کرنے دیتا ہے۔
```text
Session 1: "Add auth to the API"
Agent writes code, runs tests, fixes bugs
Connected hooks capture supported tool events
Observations become searchable project history
Session 2: "Now add rate limiting"
Agent recalls:
- 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
Continues with the earlier decisions in context.
```
### بلٹ-اِن ایجنٹ میموری کے مقابلے میں
ہر AI کوڈنگ ایجنٹ بلٹ-اِن میموری کے ساتھ آتا ہے: Claude Code کے پاس `MEMORY.md` ہے، Cursor کے پاس notepads ہیں، Cline کے پاس memory bank ہے۔ یہ sticky notes کی طرح کام کرتے ہیں۔ agentmemory ان sticky notes کے پیچھے موجود searchable ڈیٹابیس ہے۔
| | بلٹ-اِن (CLAUDE.md) | agentmemory |
|---|---|---|
| دیکھ بھال | ہاتھ سے ترتیب دی گئی ہدایات | انڈیکس شدہ سیشن کی تاریخ اور میموری |
| سرچ | سب کچھ context میں لوڈ کرتا ہے | BM25 + ویکٹر + گراف (صرف top-K) |
| کراس-ایجنٹ | فی-ایجنٹ فائلیں | MCP + REST (کوئی بھی ایجنٹ) |
| کوآرڈینیشن | کوئی نہیں | Leases، سگنلز، actions، routines |
| Observability | دستی طور پر فائلیں پڑھنا | :3113 پر ریئل-ٹائم ویور |
---
### میموری Pipeline
```text
PostToolUse hook fires
-> Stable event ID / durable capture inbox / offline spool
-> Privacy filter (strip secrets, API keys)
-> Store raw observation
-> Synthetic compression by default
(LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
-> Vector embedding when an embedding provider is active
-> Index in BM25, plus vectors when enabled
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
-> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
-> Inject context when enabled by the integration
```
### 4-درجاتی میموری استحکام (Consolidation)
یہ انسانی دماغ کے میموری پراسیس کرنے کے طریقے پر مبنی ہے، بشمول نیند کے دوران ہونے والا consolidation۔
| درجہ | کیا | مثال (Analogy) |
|------|------|---------|
| **Working** | tool use سے خام observations | قلیل مدتی میموری |
| **Episodic** | compressed سیشن خلاصے | "کیا ہوا" |
| **Semantic** | نکالے گئے facts اور patterns | "میں کیا جانتا ہوں" |
| **Procedural** | Workflows اور فیصلہ سازی کے patterns | "کیسے کرنا ہے" |
میموریز وقت کے ساتھ decay ہوتی ہیں (Ebbinghaus curve)۔ بار بار رسائی کی جانے والی میموریز مضبوط ہوتی ہیں۔ Stale میموریز خودکار طور پر evict ہو جاتی ہیں۔ تضادات (contradictions) کو detect اور resolve کیا جاتا ہے۔
### کیا کیپچر ہوتا ہے
نیچے کی جدول Claude Code کے hooks دکھاتی ہے۔ دوسرے انضمام اپنے ہوسٹ کے دستیاب واقعات ریکارڈ کرتے ہیں۔ مشترکہ hooks میں خودکار سیاق شامل کرنے کے لیے `AGENTMEMORY_INJECT_CONTEXT=true` واضح طور پر فعال کریں۔
| Hook | کیپچر کرتا ہے |
|------|----------|
| `SessionStart` | Project path، session ID |
| `UserPromptSubmit` | صارف کے prompts (privacy-filtered) |
| `PreToolUse` | File access patterns + enriched context |
| `PostToolUse` | Tool کا نام، input، output |
| `PostToolUseFailure` | Error context |
| `PreCompact` | compaction سے پہلے میموری دوبارہ انجیکٹ کرتا ہے |
| `SubagentStart/Stop` | Sub-agent lifecycle |
| `Stop` | سیشن کے اختتام کا خلاصہ |
| `SessionEnd` | سیشن مکمل ہونے کا نشان |
### اہم صلاحیتیں
| Capability | تفصیل |
|---|---|
| **خودکار کیپچر** | مقامی انضمام معاون سیشن اور ٹول واقعات ریکارڈ کرتے ہیں |
| **سیمینٹک سرچ** | RRF فیوژن کے ساتھ BM25 + ویکٹر + نالج گراف |
| **میموری ارتقا** | Versioning، سپرسیشن، تعلقات کے گراف (relationship graphs) |
| **ریکال hygiene** | سپرسیڈ شدہ میموری ورژنز سرچ indexes سے نکل جاتے ہیں؛ KV میں version chain مکمل ہسٹری رکھتی ہے |
| **Near-duplicate اشارے** | جب نیا content کسی موجودہ میموری سے قریبی مشابہت رکھتا ہے تو saves ایک advisory `similarTo` match رپورٹ کرتے ہیں |
| **فی-ایجنٹ scoping** | `agentId` REST، MCP، اور سرچ index میں save اور recall کے ذریعے، shared یا isolated موڈ میں، منتقل ہوتا ہے |
| **تحریر کے وقت کی provenance** | ہر observation اور میموری ایک غیر قابلِ تبدیل origin channel رکھتی ہے (user، agent، tool، import، یا shared) جو کیپچر، save، اور import کے وقت لگایا جاتا ہے |
| **خودکار فراموشی** | TTL expiry، تضاد کی شناخت، اہمیت کی بنیاد پر eviction |
| **پرائیویسی اولین ترجیح** | API keys، secrets، `` ٹیگز محفوظ کرنے سے پہلے ہٹا دیے جاتے ہیں |
| **خود-شفا (Self-healing)** | Circuit breaker، provider fallback chain، health monitoring |
| **Claude bridge** | MEMORY.md کے ساتھ دو طرفہ sync |
| **نالج گراف** | Entity extraction + BFS traversal |
| **ٹیم میموری** | ٹیم ممبران میں namespaced shared + private |
| **Citation provenance** | کسی بھی میموری کو اس کی ماخذ observations تک trace کریں |
| **Git snapshots** | میموری اسٹیٹ کو version، rollback، اور diff کریں |
---
تین سگنلز کو یکجا کرنے والی Triple-stream ریٹریول:
| Stream | یہ کیا کرتا ہے | کب |
|---|---|---|
| **BM25** | Synonym expansion کے ساتھ stemmed کی-ورڈ matching | ہمیشہ آن |
| **Vector** | Dense embeddings پر Cosine similarity | Embedding provider کنفیگر ہو |
| **Graph** | Entity matching کے ذریعے نالج گراف traversal | کوئری میں entities detect ہوں |
Reciprocal Rank Fusion (RRF، k=60) کے ساتھ فیوز کیا گیا اور session-diversified (فی سیشن زیادہ سے زیادہ 3 نتائج)۔
جب ویکٹر index پاپولیٹڈ ہو، `mem::search` (`memory_recall` کے پیچھے) hybrid BM25 + vector ranker استعمال کرتا ہے۔ embeddings کے بغیر یہ BM25 استعمال کرتا ہے۔ `smart-search` گراف ڈیٹا موجود ہونے پر اضافی طور پر structural graph matches بھی فیوز کر سکتا ہے۔ Lesson recall ہر کوئری پر پورے corpus کو اسکین کرنے کے بجائے ایک وقف شدہ in-memory BM25 index پر چلتا ہے۔ سپرسیڈ شدہ میموری ورژنز ہر recall راستے سے خارج ہوتے ہیں؛ version chain ان کی ہسٹری رکھتی ہے۔
[0.9.31: `AGENTMEMORY_VECTOR_BACKFILL=all` / `AGENTMEMORY_VECTOR_BACKFILL_MAX`](../docs/reliability/source-and-vector-recovery.md).
BM25 بذاتِ خود یونانی، سیریلک، عبرانی، عربی، اور accented Latin کو ٹوکنائز کرتا ہے۔ چینی / جاپانی / کوریائی میموریز کے لیے، CJK runs کو word-level tokens میں تقسیم کرنے کے لیے اختیاری segmenters (`npm install @node-rs/jieba tiny-segmenter`) انسٹال کریں؛ ان کے بغیر، agentmemory نرمی سے whole-run tokenization پر fall ہو جاتا ہے اور stderr پر ایک بار اشارہ پرنٹ کرتا ہے۔
### Embedding providers
Keyless انسٹالز ویکٹر embeddings کو غیر فعال کرتے ہیں: `mem::search` BM25 استعمال کرتا ہے، جبکہ `smart-search` موجودہ structural graph ڈیٹا بھی استعمال کر سکتا ہے۔ مفت آن-ڈیوائس سیمینٹک embeddings اختیار کرنے کے لیے، یہ `~/.agentmemory/.env` میں شامل کریں اور agentmemory دوبارہ شروع کریں:
```env
EMBEDDING_PROVIDER=local
```
عام npm install میں اختیاری `@huggingface/transformers` رن ٹائم شامل ہے۔ پہلی embedding درخواست `Xenova/all-MiniLM-L6-v2` ڈاؤن لوڈ کرتی ہے، لہٰذا اسے نیٹ ورک رسائی درکار ہے اور زیادہ وقت لگ سکتا ہے؛ اس کے بعد inference آن-ڈیوائس چلتا ہے۔ ریموٹ providers ان کی keys سے خودکار طور پر detect ہوتے ہیں جب تک `EMBEDDING_PROVIDER` انہیں override نہ کرے۔
| Provider | ماڈل | لاگت | نوٹس |
|---|---|---|---|
| **Local (تجویز کردہ opt-in)** | `all-MiniLM-L6-v2` | مفت | [`EMBEDDING_PROVIDER=local`](../README.md#embedding-providers) |
| Gemini | `gemini-embedding-001` | مفت ٹیئر | 100+ زبانیں، 768/1536/3072 dims (MRL)، 2048-ٹوکن input۔ `text-embedding-004` کی جگہ لیتا ہے ([deprecated، shutdown Jan 14, 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
| OpenAI | `text-embedding-3-small` | [OpenAI](https://openai.com/api/pricing/) | [text-embedding-3-small](https://platform.openai.com/docs/models/text-embedding-3-small) |
| Voyage AI | `voyage-code-3` | ادا شدہ (Paid) | کوڈ کے لیے optimized |
| Cohere | `embed-english-v3.0` | مفت trial | عمومی مقصد |
| OpenRouter | کوئی بھی ماڈل | مختلف ہوتا ہے | Multi-model پراکسی |
---
54 ٹولز، 6 resources، 3 prompts، اور 17 اسکلز۔
> **MCP shim بمقابلہ مکمل سرور:** شائع شدہ `@agentmemory/mcp` پیکیج ایک thin shim ہے۔ یہ مکمل 54-ٹول surface **صرف اس وقت ظاہر کرتا ہے جب یہ `AGENTMEMORY_URL` کے ذریعے کسی چلتے ہوئے agentmemory سرور تک پہنچ سکے** (proxy موڈ)۔ کوئی سرور قابلِ رسائی نہ ہونے پر، shim 7-ٹول مقامی سیٹ پر فال بیک کرتا ہے (`memory_save`، `memory_recall`، `memory_smart_search`، `memory_sessions`، `memory_export`، `memory_audit`، `memory_governance_delete`)۔ `AGENTMEMORY_TOOLS=core|all` env var ایک *سرور-سائیڈ* فلیگ ہے؛ اسے shim کے `env` بلاک میں سیٹ کرنے کا کوئی اثر نہیں ہوتا۔ اگر آپ کو Cursor / OpenCode / Gemini CLI میں صرف 7 ٹولز نظر آتے ہیں، تو `npx -y @agentmemory/agentmemory@latest` (یا Docker اسٹیک) شروع کریں اور `AGENTMEMORY_URL=http://localhost:3111` سیٹ کریں۔
### 54 ٹولز
تین tool surfaces، چھوٹے سے بڑے تک: `AGENTMEMORY_TOOLS=core` نظر آنے کی حد کو 8 بنیادی ٹولز تک محدود کرتا ہے (`memory_save`، `memory_recall`، `memory_consolidate`، `memory_smart_search`، `memory_sessions`، `memory_diagnose`، `memory_lesson_save`، `memory_reflect`)؛ نیچے دیا گیا base سیٹ registry کے 14 foundational ٹولز ہیں؛ ڈیفالٹ (`AGENTMEMORY_TOOLS=all`) تمام 54 کو ظاہر کرتا ہے۔
بنیادی ٹولز (14)
| ٹول | تفصیل |
|------|-------------|
| `memory_recall` | ماضی کی observations تلاش کریں |
| `memory_compress_file` | ساخت برقرار رکھتے ہوئے markdown فائلیں compress کریں |
| `memory_save` | کوئی insight، فیصلہ، یا pattern محفوظ کریں |
| `memory_file_history` | مخصوص فائلوں کے بارے میں ماضی کی observations |
| `memory_patterns` | بار بار آنے والے patterns detect کریں |
| `memory_sessions` | حالیہ سیشنز کی فہرست |
| `memory_smart_search` | Hybrid سیمینٹک + کی-ورڈ سرچ |
| `memory_vision_search` | image observations تلاش کریں |
| `memory_timeline` | تاریخ وار (chronological) observations |
| `memory_profile` | Project profile (concepts، files، patterns) |
| `memory_export` | تمام میموری ڈیٹا export کریں |
| `memory_relations` | relationship گراف کوئری کریں |
| `memory_commit_lookup` | کسی git commit کے پیچھے سیشنز |
| `memory_commits` | کسی سیشن کے لیے ریکارڈ شدہ commits |
وسیع ٹولز (کل 54، ڈیفالٹ surface)
| ٹول | تفصیل |
|------|-------------|
| `memory_patterns` | بار بار آنے والے patterns detect کریں |
| `memory_timeline` | تاریخ وار observations |
| `memory_relations` | relationship گراف کوئری کریں |
| `memory_graph_query` | نالج گراف traversal |
| `memory_consolidate` | 4-درجاتی consolidation چلائیں |
| `memory_claude_bridge_sync` | MEMORY.md کے ساتھ sync کریں |
| `memory_team_share` | ٹیم ممبران کے ساتھ شیئر کریں |
| `memory_team_feed` | حالیہ شیئر شدہ items |
| `memory_audit` | operations کی audit trail |
| `memory_governance_delete` | audit trail کے ساتھ ڈیلیٹ کریں |
| `memory_snapshot_create` | Git-versioned snapshot |
| `memory_action_create` | dependencies کے ساتھ work items بنائیں |
| `memory_action_update` | action کی اسٹیٹس اپ ڈیٹ کریں |
| `memory_frontier` | ترجیح کے لحاظ سے درجہ بندی شدہ unblocked actions |
| `memory_next` | واحد سب سے اہم اگلا action |
| `memory_lease` | Exclusive action leases (multi-agent) |
| `memory_routine_run` | workflow routines کو instantiate کریں |
| `memory_signal_send` | Inter-agent میسجنگ |
| `memory_signal_read` | receipts کے ساتھ messages پڑھیں |
| `memory_checkpoint` | External condition gates |
| `memory_mesh_sync` | instances کے درمیان P2P sync |
| `memory_sentinel_create` | Event-driven watchers |
| `memory_sentinel_trigger` | sentinels کو خارجی طور پر فائر کریں |
| `memory_sketch_create` | Ephemeral action graphs |
| `memory_sketch_promote` | مستقل (permanent) میں promote کریں |
| `memory_crystallize` | action chains کو compact کریں |
| `memory_diagnose` | Health checks |
| `memory_heal` | پھنسی ہوئی اسٹیٹ کو خودکار طور پر fix کریں |
| `memory_facet_tag` | Dimension:value ٹیگز |
| `memory_facet_query` | facet ٹیگز کے ذریعے کوئری کریں |
| `memory_verify` | provenance trace کریں |
### 6 Resources · 3 Prompts · 17 اسکلز
| قسم | نام | تفصیل |
|------|------|-------------|
| Resource | `agentmemory://status` | Health، session count، memory count |
| Resource | `agentmemory://project/{name}/profile` | Per-project انٹیلیجنس |
| Resource | `agentmemory://project/{name}/recent` | کسی project کی حالیہ observations |
| Resource | `agentmemory://memories/latest` | تازہ ترین 10 فعال میموریز |
| Resource | `agentmemory://graph/stats` | نالج گراف اعداد و شمار |
| Resource | `agentmemory://team/{id}/profile` | مشترک ٹیم پروفائل |
| Prompt | `recall_context` | سرچ + context پیغامات واپس کریں |
| Prompt | `session_handoff` | ایجنٹس کے درمیان ڈیٹا handoff |
| Prompt | `detect_patterns` | بار بار آنے والے patterns کا تجزیہ |
| Skill | `/recall` | میموری سرچ کریں |
| Skill | `/remember` | طویل مدتی میموری میں محفوظ کریں |
| Skill | `/session-history` | حالیہ سیشن خلاصے |
| Skill | `/forget` | observations/sessions ڈیلیٹ کریں |
یہ ٹیبل چار بنیادی اسکلز دکھاتا ہے۔ مکمل سیٹ 9 invocable اسکلز نیز 8 reference اسکلز پر مشتمل ہے؛ اوپر Native اسکلز سیکشن دیکھیں۔
### Standalone MCP
مکمل سرور کے بغیر، کسی بھی MCP کلائنٹ کے لیے چلائیں۔ ان میں سے کوئی بھی کام کرتا ہے:
```bash
npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
npx -y @agentmemory/mcp # shim package alias
```
یا اپنے ایجنٹ کی MCP کنفیگ میں شامل کریں:
زیادہ تر ایجنٹس (Cursor، Claude Desktop، Cline، Roo Code، Gemini CLI):
```json
{
"mcpServers": {
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"],
"env": {
"AGENTMEMORY_URL": "http://localhost:3111"
}
}
}
}
```
`agentmemory` entry کو فائل تبدیل کرنے کے بجائے اپنے host کے موجودہ `mcpServers` object میں ضم کریں۔ ان sandboxed کلائنٹس کے لیے جو host کے `localhost` تک نہیں پہنچ سکتے، env بلاک میں `"AGENTMEMORY_FORCE_PROXY": "1"` شامل کریں اور `AGENTMEMORY_URL` کو کسی ایسے route پر سیٹ کریں جہاں sandbox پہنچ سکے۔
OpenCode (`opencode.json`):
```json
{
"mcp": {
"agentmemory": {
"type": "local",
"command": ["npx", "-y", "@agentmemory/mcp"],
"enabled": true
}
},
"plugin": ["./plugins/agentmemory-capture.ts"]
}
```
repo سے plugin فائل کاپی کریں:
```bash
mkdir -p ~/.config/opencode/plugins
cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
```
---
پورٹ `3113` پر خودکار طور پر شروع ہوتا ہے۔ ویور جب کنکٹ ہوتا ہے تو ایک snapshot لوڈ کرتا ہے (`GET /agentmemory/viewer/snapshot`) اور پھر live stream events لاگو کرتا ہے: نئی میموریز، lessons، observations، audit entries، گراف تبدیلیاں اور health اپ ڈیٹس بغیر polling یا page reloads کے ظاہر ہوتے ہیں۔ باقی صرف وہی requests ہیں جو آپ کلک کرتے ہیں، "load more" صفحات اور سرچز۔ جب stream منقطع ہو، ویور دکھاتا ہے کہ اس کے اعداد کتنے پرانے ہیں، backoff کے ساتھ دوبارہ کنکٹ ہوتا ہے اور ایک snapshot سے دوبارہ sync کرتا ہے۔
- **چار گروپس میں 12 tabs** لائیو counts، deep links (`#memories/`، `#sessions/?obs=`، `#graph/`، `#health/consolidation`)، کی بورڈ شارٹ کٹس اور ایک موبائل مینیو کے ساتھ۔
- **Memories:** سرور-سائیڈ سرچ، project، agent اور type کے فلٹرز، version chain اور ایک word diff والا detail panel، provenance links، id کے لیے کاپی بٹنز، MCP call اور ایک curl کمانڈ، ترمیم (ایک نیا ورژن)، تصدیق کے ساتھ forget، bulk forget اور JSON export۔
- **Sessions:** قابلِ مطالعہ tool input اور output کے ساتھ ایک inline observation ٹائم لائن، فلٹرز اور paging، اور ہر سیشن نے جو میموریز اور lessons پیدا کیے۔
- **Graph:** سرچ، relations اور sources کے ساتھ node detail، ایک legend جو صرف رنگ پر انحصار نہیں کرتا، اور zoom کنٹرولز۔
- **Health:** `GET /agentmemory/status` کا لائیو ورژن۔ ہر مسئلے کے ساتھ اس کا حل آتا ہے، نیز state backend، index save state، graph provenance compaction progress اور حقیقی thresholds کے ساتھ ایک consolidation explainer۔
- **Audit، Activity، Profile، Replay، Lessons، Actions اور Crystals** صفحات، ہر ایک کی ایک empty state جو بتاتی ہے کہ سیکشن کیا ہے، یہ خالی کیوں ہے اور وہ کمانڈ جو اسے بھرتی ہے، اور ہر term اور number پر ایک `?` glossary ٹول ٹپ۔
```bash
open http://localhost:3113
```
ویور سرور ڈیفالٹ کے طور پر `127.0.0.1` سے bind ہوتا ہے اور جب یہ REST API کو requests فارورڈ کرتا ہے تو سرور secret اٹیچ کرتا ہے، لہٰذا اسے کسی سیٹ اپ کی ضرورت نہیں۔ REST کے ذریعے سرو کیا گیا `/agentmemory/viewer` اینڈ پوائنٹ عام bearer-token قواعد کی پیروی کرتا ہے اور بغیر token والے browsers کو ویور پورٹ کی طرف ری ڈائریکٹ کرتا ہے۔ CSP headers ہر response کے لیے ایک script nonce استعمال کرتے ہیں اور inline handler attributes غیر فعال کرتے ہیں (`script-src-attr 'none'`)۔
---
### LLM Providers
agentmemory آپ کے ماحول سے providers کو خودکار طور پر detect کرتا ہے۔ ایک provider LLM پر مبنی operations کو دستیاب بناتا ہے، لیکن صرف provider کنفیگریشن LLM کی تحریر کردہ observation compression کو فعال نہیں کرتی۔ اس راستے کو provider اور `AGENTMEMORY_AUTO_COMPRESS=true` دونوں درکار ہیں۔
| Provider | کنفیگ | نوٹس |
|----------|--------|-------|
| **No-op (ڈیفالٹ)** | کسی کنفیگ کی ضرورت نہیں | LLM پر مبنی compress/summarize غیر فعال ہے۔ Synthetic compression اور BM25 recall بدستور کام کرتے ہیں۔ اگر آپ Claude-subscription fallback پر انحصار کرتے تھے تو نیچے `AGENTMEMORY_ALLOW_AGENT_SDK` دیکھیں۔ |
| Anthropic API | `ANTHROPIC_API_KEY` | فی-ٹوکن بلنگ |
| MiniMax | `MINIMAX_API_KEY` | Anthropic-compatible |
| Gemini | `GEMINI_API_KEY` | embeddings بھی فعال کرتا ہے |
| OpenRouter | `OPENROUTER_API_KEY` | کوئی بھی ماڈل |
| OpenAI API | `OPENAI_API_KEY` | ڈیفالٹ `gpt-5.6-luna`، `OPENAI_MODEL` سے override کریں |
| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) یا `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | کوئی بھی OpenAI-API-compatible چیز۔ صفر لاگت، آپ کے اپنے hardware پر چلتا ہے۔ نیچے [مقامی ماڈلز](#local-models-ollama--lm-studio--vllm) دیکھیں۔ |
| Claude subscription fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | صرف opt-in۔ `@anthropic-ai/claude-agent-sdk` سیشنز spawn کرتا ہے؛ یہ پہلے لامحدود Stop-hook recursion کا سبب بنتا تھا، لہٰذا یہ اب ڈیفالٹ نہیں ہے۔ |
### مقامی ماڈلز (Ollama / LM Studio / vLLM)
agentmemory کسی بھی OpenAI-API-compatible سرور سے بات کرتا ہے، لہٰذا جو کچھ بھی `/v1/chat/completions` ایکسپوز کرتا ہے وہ بغیر کوڈ تبدیلیوں کے کام کرتا ہے۔ کوئی ادا شدہ keys نہیں، کوئی کلاؤڈ نہیں، کوئی rate limits نہیں؛ مکمل طور پر آپ کے اپنے hardware پر چلتا ہے۔
**Ollama** (ڈیفالٹ پورٹ `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** (ڈیفالٹ پورٹ `1234`):
LM Studio کھولیں → Local Server tab → Start Server۔ picker سے کوئی بھی chat ماڈل منتخب کریں (Qwen 3، gpt-oss، DeepSeek R1، وغیرہ)۔
```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**: وہی شکل۔ `OPENAI_BASE_URL` کو اس URL کی طرف پوائنٹ کریں جو آپ کا سرور ایکسپوز کرتا ہے اور `OPENAI_MODEL` کو ایسے نام پر سیٹ کریں جسے آپ کا سرور قبول کرے۔
**میموری کام کے لیے ماڈل انتخاب**: compression اور summarization مختصر tasks ہیں (<2K ٹوکنز اندر، <500 ٹوکنز باہر) جہاں ایک 7B instruct ماڈل کافی ہے۔ تجاویز:
| ماڈل | سائز | کیوں |
|-------|------|-----|
| `qwen3:8b` | ~5.2 GB | 16 GB مشین پر متوازن ڈیفالٹ؛ extraction اور tool-shaped text میں مضبوط |
| `qwen3:4b` | ~2.6 GB | سب سے چھوٹا مناسب آپشن؛ compression کے لیے ٹھیک، graph extraction کے لیے کمزور |
| `qwen3-coder:30b` | ~19 GB | 24-32 GB hardware پر code-shaped سیشنز کے لیے بہترین مقامی انتخاب (30B MoE، 3.3B active) |
| `gpt-oss:20b` | ~14 GB | ایک مضبوط عمومی ماڈل جو 16 GB RAM میں فٹ ہو جاتا ہے |
| `deepseek-r1:8b` | ~5.2 GB | Reasoning distill؛ سست لیکن صاف تر extractions |
Qwen 3 ماڈلز ڈیفالٹ کے طور پر سوچتے (think) ہیں اور کسی بھی output سے پہلے پورا token بجٹ reasoning پر خرچ کر سکتے ہیں۔ graph-extraction prompts میں `/no_think` شامل کرنے کے لیے `AGENTMEMORY_LLM_NOTHINK=1` سیٹ کریں، اور اگر extractions خالی واپس آئیں تو `MAX_TOKENS` بڑھائیں (16384 کام کرتا ہے)۔
Reasoning-class ماڈلز (`` بلاکس کے ساتھ `o1`-طرز) خالی `content` واپس کر سکتے ہیں جس کے ساتھ ایک `reasoning` field ہو جو آپ کا مقامی سرور ظاہر نہ کرے۔ اگر extractions خالی آئیں، تو پہلے کسی non-reasoning ماڈل پر سوئچ کریں۔ `OPENAI_REASONING_EFFORT=none` env ان Ollama Cloud thinking ماڈلز پر بھی thinking غیر فعال کر سکتا ہے جو OpenAI reasoning schema کی نقل کرتے ہیں۔
مقامی embeddings ایک اختیاری dependency کے طور پر شپ ہوتی ہیں لیکن ڈیفالٹ کے طور پر فعال نہیں ہوتیں۔ `Xenova/all-MiniLM-L6-v2` (384-dim) اختیار کرنے کے لیے `EMBEDDING_PROVIDER=local` سیٹ کریں۔ پہلی embedding درخواست ماڈل ڈاؤن لوڈ کرتی ہے؛ اس کے بعد inference آن-ڈیوائس ہوتا ہے۔ اس سیٹنگ یا کسی ریموٹ embedding key کے بغیر، ویکٹرز غیر فعال رہتے ہیں، `mem::search` BM25 استعمال کرتا ہے، اور `smart-search` پھر بھی موجودہ graph matches شامل کر سکتا ہے۔
### لاگت سے آگاہ ماڈل انتخاب
بغیر کلید کے capture اور لفظی تلاش سے شروع کریں۔ `EMBEDDING_PROVIDER=local` پہلے ماڈل ڈاؤن لوڈ کے بعد آلے پر معنوی تلاش فراہم کرتا ہے۔ LLM کمپریشن میں فراہم کنندہ اور `AGENTMEMORY_AUTO_COMPRESS=true` ضروری ہیں؛ ہر مشاہدے پر درخواست ہو سکتی ہے، اس لیے موجودہ قیمت دیکھیں۔
`agentmemory status` / http://localhost:3113
### ملٹی-ایجنٹ میموری (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
ایسے multi-agent سیٹ اپس میں جہاں کئی roles ایک agentmemory سرور کا اشتراک کرتے ہیں (architect / developer / reviewer / researcher / support-agent)، `AGENT_ID` ہر write کو اس role کے ساتھ ٹیگ کرتا ہے جس نے وہ کیا۔ `AGENTMEMORY_AGENT_SCOPE` کنٹرول کرتا ہے کہ آیا recall اس ٹیگ کے لحاظ سے فلٹر کرے۔
```env
TEAM_ID=company
USER_ID=engineering-team
AGENT_ID=architect
AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
```
| موڈ | Writes ٹیگ ہوں | Recall فلٹر ہو | کب استعمال کریں |
|------|------------|---------------|-------------|
| `shared` (ڈیفالٹ) | ہاں | نہیں | audit trail کے ساتھ cross-agent context۔ Architect دیکھ سکتا ہے کہ developer نے کیا نوٹ کیا، لیکن ہر row ریکارڈ کرتی ہے کہ کس نے کہا۔ |
| `isolated` | ہاں | ہاں | سخت علیحدگی۔ Architect کبھی developer کی observations / memories / sessions نہیں دیکھتا۔ |
جب `AGENT_ID` سیٹ ہو تو کیا ٹیگ ہوتا ہے: `Session.agentId`، `RawObservation.agentId`، `CompressedObservation.agentId`، `Memory.agentId`۔ role `api::session::start` → `mem::observe` → `mem::compress` → KV سے گزرتا ہے۔
isolated موڈ میں کیا فلٹر ہوتا ہے: `mem::smart-search`، `/agentmemory/memories`، `/agentmemory/observations`، `/agentmemory/sessions`۔ ہر endpoint فی-request override کرنے کے لیے `?agentId=` قبول کرتا ہے، اور env scope سے مکمل طور پر opt out کرنے کے لیے `?agentId=*`۔ `/memories` ان pre-AGENT_ID میموریز کو ظاہر کرنے کے لیے `?includeOrphans=true` بھی قبول کرتا ہے جن کا `agentId` undefined ہے۔
SDK / REST سطح پر فی-call override: ہر mutating endpoint (`/session/start`، `/remember`) request body میں ایک `agentId` field قبول کرتا ہے جو env پر فوقیت رکھتا ہے۔ ان runtimes کے لیے مفید جو کئی roles کو ایک سرور process کے ذریعے روٹ کرتے ہیں۔ MCP کا `memory_save` ٹول وہی `agentId` field ظاہر کرتا ہے، standalone stdio سرور `agentId` اور `project` دونوں فارورڈ کرتا ہے، اور محفوظ شدہ میموریز `agentId` کو سرچ index میں لے جاتی ہیں، لہٰذا agent-scoped سرچ observations کے ساتھ ساتھ memories کو بھی کَوَر کرتی ہے۔
جب `AGENT_ID` سیٹ نہ ہو، میموری unscoped رہتی ہے (legacy رویہ، کوئی ٹیگز نہیں، کوئی فلٹرز نہیں)۔
### پورٹس
API اور ویوئر بطور طے شدہ loopback استعمال کرتے ہیں۔
| Port | API / ویوئر | Env |
|---|---|---|
| `3111` | REST / MCP / SSE | `III_REST_PORT` |
| `3113` | ویوئر | `III_VIEWER_PORT` |
`--port ` API پورٹ مقرر کرتا ہے؛ ویوئر بطور طے شدہ `N+2` استعمال کرتا ہے۔ الگ انسٹینس کے لیے `--instance N` استعمال کریں۔ اندرونی listeners نجی رکھیں۔ دور سے رسائی اور [پرانے Docker کی منتقلی](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) کے لیے ڈیپلائمنٹ گائیڈ دیکھیں۔
### اسٹوریج backend: file (ڈیفالٹ) بمقابلہ redis
الگ ڈیٹابیس سروس درکار نہیں. Redis: `AGENTMEMORY_STATE_BACKEND=redis` + `AGENTMEMORY_REDIS_URL`. بیک اینڈ بدلنے سے موجودہ میموری خود بخود نقل نہیں ہوتی۔ [ڈیٹا اسٹوریج](../docs/reliability/state-storage.md).
### کنفیگ فائل
ہر shell میں variables export کرنے کے بجائے runtime config کو `~/.agentmemory/.env` میں رکھیں۔ دوسری env-file کے لیے `AGENTMEMORY_ENV_FILE` مقرر کریں۔ Process environment variables فائل پر فوقیت رکھتے ہیں۔ CLI کا Worker Compose Redis settings کو `state` worker تک پہنچاتا ہے۔
```powershell
New-Item -ItemType Directory -Force $HOME\.agentmemory
notepad $HOME\.agentmemory\.env
```
API key کے بجائے Claude Code Pro/Max subscription کے ساتھ ٹیسٹ کرنے کے لیے، واضح طور پر opt in کریں:
```env
AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true
```
LLM کی تحریر کردہ observation compression کو دونوں سطریں درکار ہیں: کسی LLM provider تک رسائی (بشمول یہ واضح subscription fallback) اور `AGENTMEMORY_AUTO_COMPRESS=true`۔ صرف ایک provider ڈیفالٹ synthetic compression راستے کو برقرار رکھتا ہے۔
Consolidation (graph nodes، lessons، crystals) جب بھی کوئی LLM provider کنفیگر ہو تو ڈیفالٹ کے طور پر آن ہوتا ہے۔ اگر آپ LLM-free آپریشن چاہتے ہیں تو `CONSOLIDATION_ENABLED=false` کے ساتھ واضح طور پر opt out کریں۔ Graph extraction ایک علیحدہ flag ہے:
```env
GRAPH_EXTRACTION_ENABLED=true
# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
```
### ماحولیاتی Variables
`~/.agentmemory/.env`:
```env
EMBEDDING_PROVIDER=local
# AGENTMEMORY_INJECT_CONTEXT=true
# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
# AUTO_FORGET_ENABLED=false
# LESSON_DECAY_ENABLED=false
# INSIGHT_DECAY_ENABLED=false
```
مکمل ترتیب [`.env.example`](../.env.example) میں ہے، بشمول فراہم کنندہ، capture filters، مدتِ تحفظ، اسٹوریج اور ٹیم کا دائرہ۔ `AGENTMEMORY_ENV_FILE` سے دوسری فائل منتخب کریں۔ تبدیلی کے بعد دوبارہ آغاز کریں۔ حقیقی اقدار والی `.env` یا Bearer راز commit نہ کریں۔
---
پورٹ `3111` پر 147 اینڈ پوائنٹس۔ REST API ڈیفالٹ کے طور پر `127.0.0.1` سے bind ہوتا ہے۔ محفوظ اینڈ پوائنٹس کو `Authorization: Bearer ` درکار ہے، اور mesh sync اینڈ پوائنٹس کو دونوں peers پر واضح طور پر سیٹ کیا گیا `AGENTMEMORY_SECRET` درکار ہے۔
توثیق بطور طے شدہ فعال ہے۔ `AGENTMEMORY_SECRET` مقرر نہ ہو تو CLI پہلی بار بے ترتیب راز `~/.agentmemory/secret` میں محفوظ کرتا ہے اور منتخب ڈیٹا ڈائریکٹری کے `secret` میں اس کی نقل رکھتا ہے؛ اجازت `0600` ہوتی ہے۔ ساتھ آنے والے کلائنٹس مقامی رابطے میں اس اصل فائل کو ترجیح دیتے ہیں اور محفوظ راز صرف loopback URL کو بھیجتے ہیں۔ واضح `AGENTMEMORY_SECRET` مقدم ہے؛ دور کے کلائنٹس اسے environment میں مقرر کریں۔ Docker اپنا راز بناتا ہے۔
```bash
curl -H "Authorization: Bearer " http://localhost:3111/agentmemory/health
```
**Writes کے لیے request قواعد۔** REST API اور ویور کو بھیجی جانے والی `POST`، `PUT`، `PATCH` اور `DELETE` درخواستوں کو جب بھی ان کے ساتھ body ہو تو `Content-Type: application/json` بھیجنا ضروری ہے (ایک `charset` پیرامیٹر ٹھیک ہے)، اور ایک `Origin` ہیڈر، جب موجود ہو، کو کنفیگر کردہ REST یا viewer پورٹ کے لیے loopback origin ہونا چاہیے یا `VIEWER_ALLOWED_ORIGINS` میں درج ہونا چاہیے (comma-separated، مثلاً `https://memory.example.com`)۔ وہ کلائنٹس جو کوئی `Origin` ہیڈر نہیں بھیجتے (CLI، hooks، MCP، curl، server-to-server) متاثر نہیں ہوتے۔ ویور اپنا origin بھی قبول کرتا ہے۔
**فائل Paths۔** وہ اینڈ پوائنٹس جو فائلیں پڑھتے یا لکھتے ہیں (`/compress-file`، `/replay/import-jsonl`، `/graph/import-graphify`) صرف `~/.agentmemory`، instance data ڈائرکٹری، یا `AGENTMEMORY_IMPORT_ROOT` میں درج کسی ڈائرکٹری کے تحت paths قبول کرتے ہیں (کئی کو `:` سے، یا Windows پر `;` سے الگ کریں)۔ `/replay/import-jsonl` اپنا ڈیفالٹ `~/.claude/projects` بھی قبول کرتا ہے۔ `/obsidian/export` `AGENTMEMORY_EXPORT_ROOT` کے اندر اور `/migrate` `~/.agentmemory` کے اندر رہتا ہے۔ Symlinks ہر چیک سے پہلے resolve کیے جاتے ہیں۔
**Secret Scrubbing۔** API keys، bearer tokens، PEM private key بلاکس اور URLs میں embedded credentials (`scheme://user:password@host`) ہر write راستے پر متن محفوظ ہونے سے پہلے redact کر دیے جاتے ہیں: observations، remember، evolve، slots، lessons، actions، sketches، signals، checkpoints، imports، jsonl replay، mesh sync، team shares، compression اور summary output، crystals اور graph nodes۔
اہم اینڈ پوائنٹس
| Method | Path | تفصیل |
|--------|------|-------------|
| `GET` | `/agentmemory/health` | Health check (ہمیشہ عوامی) |
| `GET` | `/agentmemory/status` | کیا غلط ہے اور اسے کیسے ٹھیک کریں (browsers کے لیے HTML، ورنہ JSON) |
| `GET` | `/agentmemory/viewer/snapshot` | ویور جو کچھ دکھاتا ہے، ایک ہی response میں |
| `POST` | `/agentmemory/session/start` | سیشن شروع کریں + context حاصل کریں |
| `POST` | `/agentmemory/session/end` | سیشن ختم کریں |
| `POST` | `/agentmemory/observe` | observation کیپچر کریں (نیچے capture delivery دیکھیں) |
| `GET` | `/agentmemory/capture` | Capture inbox، dead letters اور offline spool |
| `POST` | `/agentmemory/capture/retry` | Dead-letter کیپچرز دوبارہ کریں |
| `POST` | `/agentmemory/capture/drain` | مقامی offline spool ابھی بھیجیں |
| `POST` | `/agentmemory/smart-search` | Hybrid سرچ |
| `POST` | `/agentmemory/context` | Context تیار کریں |
| `POST` | `/agentmemory/remember` | طویل مدتی میموری میں محفوظ کریں |
| `POST` | `/agentmemory/forget` | Observations ڈیلیٹ کریں |
| `POST` | `/agentmemory/enrich` | File context + memories + bugs |
| `GET` | `/agentmemory/profile` | Project profile |
| `GET` | `/agentmemory/export` | تمام ڈیٹا export کریں |
| `POST` | `/agentmemory/import` | JSON سے import کریں |
| `POST` | `/agentmemory/graph/query` | نالج گراف کوئری |
| `POST` | `/agentmemory/graph/compact` | زائد الحجم graph provenance کو trim کریں |
| `POST` | `/agentmemory/team/share` | ٹیم کے ساتھ شیئر کریں |
| `GET` | `/agentmemory/audit` | Audit trail |
مکمل اینڈ پوائنٹ فہرست: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
**کیپچر ڈیلیوری۔** Hooks ہر observation کو ایک بار `eventId` کے ساتھ `POST /agentmemory/observe` پر بھیجتے ہیں۔ جب payload میں ایک موجود ہو (مثلاً Claude Code کا `tool_use_id`) تو یہ کال کے لیے host کا اپنا id ہوتا ہے، ورنہ سیشن، hook type، tool نام، input، output اور host timestamp کا ایک hash۔ سرور event کو state store میں ایک capture inbox میں لکھتا ہے، observation محفوظ کرتا ہے، پھر inbox entry ہٹا دیتا ہے۔ status code بتاتا ہے کیا ہوا:
| Status | `status` field | معنی |
|---|---|---|
| `201` | `accepted` | محفوظ ہو گیا۔ `observationId` نئی observation ہے۔ |
| `202` | `accepted` (`state: "retrying"`) | Accepted، لیکن محفوظ کرنا ناکام ہوا۔ سرور اسے دوبارہ کوشش کرتا ہے، ریسٹارٹ کے بعد بھی۔ |
| `200` | `duplicate` | یہ `eventId` پہلے ہی قبول کیا جا چکا تھا۔ `observationId` موجودہ observation ہے؛ کچھ نیا محفوظ نہیں ہوتا۔ |
| `400` / `422` | `rejected` | غلط payload، یا محفوظ کرنا مستقل طور پر ناکام ہوا (event ایک dead letter کے طور پر رکھا جاتا ہے)۔ |
| `503` | `rejected` (`retryable: true`) | Inbox بھرا ہوا ہے (`AGENTMEMORY_CAPTURE_INBOX_MAX`)۔ Hooks event کو spool کرتے ہیں اور بعد میں بھیجتے ہیں۔ |
ناکام events کو ہر `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 ثانیے) بعد doubling backoff کے ساتھ دوبارہ کوشش کی جاتی ہے، `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5) تک۔ وہ events جو بدستور ناکام رہیں inbox میں dead letters کے طور پر رہتے ہیں، `/agentmemory/status` اور ویور کے Health صفحے پر درج ہوتے ہیں، اور `POST /agentmemory/capture/retry` (`{"eventId": "..."}` یا `{"all": true}`) سے دوبارہ کوشش کی جا سکتی ہے۔ قبول شدہ event ids کو `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 گھنٹے، زیادہ سے زیادہ `AGENTMEMORY_CAPTURE_EVENTS_MAX` ids) تک یاد رکھا جاتا ہے، لہٰذا کوئی hook جو timeout یا ریسٹارٹ کے بعد دوبارہ چلایا جائے وہ ایک بار محفوظ ہوتا ہے، جبکہ اپنے اپنے host ids والی دو علیحدہ tool calls دو بار محفوظ ہوتی ہیں چاہے ان کا content یکساں ہو۔ جب کوئی observation ڈیلیٹ ہوتی ہے (forget، session delete، eviction، auto-forget یا کوئی import جو store کو replace کرے)، تو observation ہٹائے جانے سے پہلے اس کا event deleted کے طور پر نشان زد کیا جاتا ہے، لہٰذا اسی window کے اندر اس event کا کوئی replay duplicate کے طور پر جواب دیا جاتا ہے اور کچھ محفوظ نہیں ہوتا۔ state store ہر 2 سیکنڈ بعد ڈسک پر لکھتا ہے، لہٰذا کوئی جواب دیا گیا event ابھی بھی ایک لمحے کے لیے صرف میموری میں ہو سکتا ہے۔ اسے کَوَر کرنے کے لیے، ہر `2xx` جواب سرور کا `bootId` (ہر اسٹارٹ پر نیا)، `acceptedAt` اور `durableAfterMs` بھی لے جاتا ہے (save interval نیز file store پر 1.5 سیکنڈ، redis پر 1.5 سیکنڈ، جہاں persistence آپریٹر کی سیٹنگ ہے)۔ Hooks event کو مقامی spool میں اس وقت تک رکھتے ہیں جب تک وہ window گزر نہ جائے اور اسے کسی بعد کی call پر بغیر کسی اور request کے ڈیلیٹ کر دیتے ہیں۔ اگر اس دوران `bootId` بدل گیا ہو، تو سرور ریسٹارٹ ہوا تھا، لہٰذا hook وہی `eventId` کے ساتھ event دوبارہ بھیجتا ہے؛ جو event ڈسک تک پہنچ چکا تھا وہ دو بار محفوظ نہیں ہوتا۔ سرور خود بھی ایسے events کو اسٹارٹ پر اور ہر retry interval پر بھیجتا ہے، لہٰذا ریسٹارٹ کے بعد بھی اگر کوئی hook نہ چلے تو کچھ نہیں کھوتا۔ پرانے hooks اضافی fields کو نظرانداز کرتے ہیں، اور کسی پرانے سرور کے خلاف نئے hooks `2xx` پر event کو ویسے ہی discard کر دیتے ہیں جیسے پہلے کرتے تھے۔
جب سرور بند ہو، وقت پر جواب نہ دے یا 5xx واپس کرے، تو hook observation کو ایک مقامی spool فائل میں شامل کرتا ہے، `/capture-spool/-.jsonl` (فولڈر کو `AGENTMEMORY_CAPTURE_SPOOL_DIR` سے override کریں)۔ فائل آپ کے صارف کے لیے نجی ہے (mode 600)، secrets اسی طرح redact ہوتے ہیں جیسے سرور انہیں redact کرتا ہے، یہ زیادہ سے زیادہ `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) رکھتی ہے اور `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168) سے پرانے entries گرا دیتی ہے۔ جب یہ بھر جائے، نئے entries گرا دیے جاتے ہیں اور ان کو شمار کیا جاتا ہے، اور `/agentmemory/status` اس کی رپورٹ کرتا ہے۔ hook پھر بھی اپنی وقت کی حد کے اندر 0 کے ساتھ exit ہوتا ہے اور جب سرور صحت مند ہو تو کوئی اضافی request نہیں بڑھاتا۔ spool اگلے اسٹارٹ پر اور پہلے hook کے ذریعے جو سرور تک دوبارہ پہنچے، ایک background process میں بھیجا جاتا ہے تاکہ ایجنٹ انتظار نہ کرے۔ Event ids اسے محفوظ بناتے ہیں: کوئی observation جو timeout سے پہلے پہنچ چکی ہو وہ دو بار محفوظ نہیں ہوتی۔ `npx @agentmemory/agentmemory capture` spool اور سرور inbox دکھاتا ہے، `--drain` ابھی spool بھیجتا ہے، اور `GET /agentmemory/capture` وہی JSON کے طور پر واپس کرتا ہے۔ spool بند کرنے کے لیے `AGENTMEMORY_CAPTURE_SPOOL=false` سیٹ کریں۔
**Graph Provenance کو Compact کرنا۔** پرانے provenance کی compaction اسٹارٹ اپ پر مؤخر رہتی ہے کیونکہ یہ پرانے scopes کو مکمل پڑھتی ہے۔ `/agentmemory/status` میں `deferred`، یا `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` ہونے پر `off` دکھائی دیتا ہے۔ نیچے دی گئی دستی compaction دیکھ بھال کے دوران چلائیں۔ Retrieval index کی migration الگ ہے: [دیکھ بھال کی گائیڈ](../docs/reliability/graph-index-migration.md) کے مطابق `agentmemory graph-index migrate --allow-legacy-scan` استعمال کریں۔
اسے دستی طور پر چلانے کے لیے، `POST /agentmemory/graph/compact` کال کریں۔ یہ ہر node اور edge کی فہرست بنانے کے بجائے name اور edge-key indexes پر چلتا ہے، اور دوبارہ چلانا محفوظ ہے۔ جب یہ ids trim کرتا ہے تو ایک `graph_compact` audit entry لکھتا ہے۔
```bash
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{}'
```
کسی بڑے store پر، یا جب call 504 واپس کرے، تو اسے slices میں چلائیں۔ `scope` (`nodes`، `edges` یا `history`)، `offset` اور `limit` بھیجیں، پھر واپس آئے گئے `nextOffset` کے ساتھ دوبارہ کال کریں جب تک یہ `null` نہ ہو جائے۔ یہ `nodes`، `edges` اور `history` کے لیے کریں، اور ایک `{"scope":"snapshot"}` call کے ساتھ ختم کریں، کیونکہ sliced run cached snapshot کو نہیں چھیڑتا۔
```bash
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
```bash
npm run dev # Hot reload
npm run build # Production build
npm test # 5,000+ tests
npm run test:integration # API tests (requires running services)
```
ضروریات [تنصیب](#install) اور تعاون و ریلیز کی جانچ [CONTRIBUTING.md](../CONTRIBUTING.md) میں ہیں۔