آپ کا کوڈنگ ایجنٹ سب کچھ یاد رکھتا ہے۔ دوبارہ وضاحت کرنے کی ضرورت نہیں۔ iii engine پر تیار کیا گیا
Claude Code، GitHub Copilot CLI، Cursor، Gemini CLI، Codex CLI، Hermes، OpenClaw، pi، OpenCode، اور کسی بھی MCP کلائنٹ کے لیے مستقل میموری۔

یہ گسٹ Karpathy کے LLM Wiki پیٹرن کو کانفیڈنس اسکورنگ، لائف سائیکل، نالج گرافس، اور ہائبرڈ سرچ کے ساتھ وسعت دیتا ہے: agentmemory اسی کا عملی نفاذ ہے۔

95.2% ریٹریول R@5 92% کم ٹوکنز 54 MCP ٹولز 12 خودکار ہکس 0 خارجی ڈیٹابیسز 2,500+ ٹیسٹس پاس ہو رہے ہیں

agentmemory ڈیمو

انسٹال • فوری آغاز • بینچ مارکس • حریفوں کے مقابلے میں • ایجنٹس • یہ کیسے کام کرتا ہے • MCP • ویور • iii سے تقویت یافتہ • کنفیگ • API

--- ## انسٹال تقاضے: - Node.js 20 یا نیا، npm اور npx کے ساتھ (`node -v`، `npm -v`، اور `npx -v`)۔ - macOS/Linux پر خودکار iii-engine انسٹالیشن کے لیے `curl`، ایک POSIX `sh`، اور `tar` بھی ضروری ہیں۔ `node:20-slim` جیسی minimal images میں یہ شامل نہیں ہو سکتے۔ - نیٹیو Windows کے لیے pinned iii-engine v0.22.1 `iii.exe` کو دستی طور پر انسٹال کرنا ضروری ہے۔ WSL2 یا Docker Desktop دیگر معاون راستے ہیں۔ معیاری fresh-install کمانڈ: ```bash npx -y @agentmemory/agentmemory@latest ``` پہلی بار چلانے پر ایک انٹرایکٹو سیٹ اپ ہوتا ہے: جن ایجنٹس کو جوڑنا ہے انہیں منتخب کریں (Claude Code، Cursor، Codex، Gemini CLI، OpenCode، ...)، کوئی LLM پرووائیڈر منتخب کریں یا بغیر کلید (keyless) کے رہیں، اور یہ کنفیگ تیار کرتا ہے، میموری سرور اور اس کا pinned iii engine شروع کرتا ہے، اور عالمی سطح پر انسٹال کرنے کی پیشکش کرتا ہے تاکہ صرف `agentmemory` کمانڈ بعد میں ہر جگہ کام کرے۔ `-y` npx کے پیکیج پرامپٹ کو قبول کرتا ہے اور `@latest` کسی پرانے cached ریلیز سے بچاتا ہے۔ ایک پرووائیڈر LLM خصوصیات کو دستیاب بناتا ہے، لیکن LLM کی تحریر کردہ observation compression تب ہی شروع ہوتی ہے جب `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 مقامی طور پر چلتا ہے۔ مقامی رن ٹائم چار پورٹس استعمال کرتا ہے: REST/MCP HTTP کے لیے `3111`، iii streams کے لیے `3112`، ویور کے لیے `3113`، اور iii ورکر WebSocket کے لیے `49134`۔ مستقل iii اسٹیٹ macOS پر `~/Library/Application Support/agentmemory`، Linux پر `$XDG_DATA_HOME/agentmemory` یا `~/.local/share/agentmemory`، اور Windows پر `%APPDATA%\agentmemory` میں رہتی ہے۔ اسے اووررائیڈ کرنے کے لیے `--data-dir ` یا `AGENTMEMORY_DATA_DIR` استعمال کریں، اور ہر ریسٹارٹ پر وہی قدر دہرائیں۔ بیک ورڈ compatibility کے لیے، موجودہ `./data/state_store.db` یا `./data/iii-config.yaml` انسٹنس 0 کے لیے پلیٹ فارم ڈیفالٹ پر فوقیت رکھتا ہے؛ ایک واضح فلیگ یا ماحولیاتی اوور رائیڈ پھر بھی جیت جاتا ہے۔ پھر ثابت کریں کہ ریکال کام کر رہا ہے اور اپنے ایجنٹ کو اس کی اسکلز دیں: ```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 ` سے مزید ایجنٹس جوڑیں — 20 adapters [ہر ایجنٹ کے ساتھ کام کرتا ہے](#works-with-every-agent) میں درج ہیں۔ مکمل کمانڈ ریفرنس [فوری آغاز](#quick-start) میں ہے۔

Windows

سب سے تیز راستہ WSL2 ہے۔ نیٹیو Windows انجن سیٹ اپ کے لیے pinned v0.22.1 ZIP ڈاؤن لوڈ کرنا اور `iii.exe` کو دستی طور پر ایکسٹریکٹ کرنا ضروری ہے؛ CLI اسے خودکار طور پر ایکسٹریکٹ نہیں کرتا۔ Docker Desktop بھی معاون ہے۔ مرحلہ وار تفصیل کے لیے [Windows نوٹس](#windows) دیکھیں۔

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` ڈیلیٹ کریں)۔

آپ کا اپنا iii engine پہلے سے چل رہا ہے

agentmemory iii-engine v0.22.1 کو pin کرتا ہے اور کسی مختلف ورژن سے منسلک نہیں ہوتا (ورکر کسی دوسرے انجن کا پروٹوکول نہیں بول سکتا)۔ دوسرا انجن روکیں، پھر `npx -y @agentmemory/agentmemory@latest` چلائیں۔ یہ pinned v0.22.1 کو `~/.agentmemory/bin` میں انسٹال اور چلاتا ہے، جبکہ آپ کا اپنا `iii` بغیر چھیڑے رہتا ہے۔

---

agentmemory کسی بھی ایسے ایجنٹ کے ساتھ کام کرتا ہے جو hooks، MCP، یا REST API کو سپورٹ کرتا ہو۔ تمام ایجنٹس ایک ہی میموری سرور کا اشتراک کرتے ہیں۔

Claude Code _{نیٹیو پلگ ان + 12 ہکس + MCP}	Codex CLI _{نیٹیو پلگ ان + 6 ہکس + MCP}	GitHub Copilot CLI _{MCP + پلگ ان ہکس/اسکلز}	Cursor _{نیٹیو پلگ ان + 7 ہکس + MCP}	OpenCode _{کیپچر پلگ ان + MCP}
Devin _{6 ہکس + اسکلز + MCP}	OpenClaw _{نیٹیو پلگ ان + MCP}	Hermes _{نیٹیو پلگ ان + MCP}	pi _{نیٹیو پلگ ان + MCP}	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 _{MCP سرور}	Roo Code _{MCP سرور}	Kilo Code _{MCP سرور}	Goose _{MCP سرور}	Aider _{REST API}

_{MCP یا HTTP بولنے والے کسی بھی ایجنٹ کے ساتھ کام کرتا ہے۔ ایک سرور، میموریز ان سب کے درمیان مشترک ہیں۔}

--- آپ ہر سیشن میں وہی architecture دوبارہ بیان کرتے ہیں۔ آپ وہی bugs دوبارہ ڈھونڈتے ہیں۔ آپ وہی ترجیحات دوبارہ سکھاتے ہیں۔ بلٹ-اِن میموری (CLAUDE.md، .cursorrules) 200 لائنز پر رک جاتی ہے اور پرانی ہو جاتی ہے۔ agentmemory یہ مسئلہ حل کرتا ہے۔ یہ خاموشی سے وہ سب کچھ ریکارڈ کرتا ہے جو آپ کا ایجنٹ کرتا ہے، اسے searchable میموری میں compress کرتا ہے، اور اگلا سیشن شروع ہوتے ہی درست context انجیکٹ کرتا ہے۔ صرف ایک کمانڈ۔ تمام ایجنٹس پر کام کرتا ہے۔ **کیا بدلتا ہے:** سیشن 1 میں آپ JWT auth سیٹ اپ کرتے ہیں۔ سیشن 2 میں آپ rate limiting مانگتے ہیں۔ ایجنٹ کو پہلے ہی معلوم ہے کہ آپ کا auth `src/middleware/auth.ts` میں jose middleware استعمال کرتا ہے، آپ کے ٹیسٹس token validation کو کَوَر کرتے ہیں، اور آپ نے Edge compatibility کے لیے jsonwebtoken کے بجائے jose کو چنا تھا، بغیر کسی دوبارہ وضاحت یا کاپی-پیسٹ کے۔ ```bash npx -y @agentmemory/agentmemory@latest ``` ڈیفالٹ کے طور پر، agentmemory iii-engine کی اسٹیٹ اس repository سے باہر محفوظ کرتا ہے جہاں سے آپ اسے شروع کرتے ہیں: macOS پر `~/Library/Application Support/agentmemory`، Linux پر `$XDG_DATA_HOME/agentmemory` یا `~/.local/share/agentmemory`، اور Windows پر `%APPDATA%\agentmemory`۔ موجودہ legacy `./data/state_store.db` یا `./data/iii-config.yaml` کو اس پلیٹ فارم ڈیفالٹ سے پہلے انسٹنس 0 کے لیے دوبارہ استعمال کیا جاتا ہے۔ کوئی مقام واضح طور پر منتخب کرنے کے لیے، `--data-dir ` پاس کریں یا `AGENTMEMORY_DATA_DIR` سیٹ کریں؛ دونوں میں سے کوئی بھی واضح سیٹنگ legacy discovery پر فوقیت رکھتی ہے: ```bash npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest ``` نیٹیو اور Docker دونوں لانچز اسی resolved ہوسٹ ڈائرکٹری کو استعمال کرتے ہیں؛ Docker اسے `/data` پر bind-mount کرتا ہے۔ `--instance 1` resolved ڈائرکٹری میں `instance-1` شامل کرتا ہے اور علیحدہ ڈیفالٹ پورٹ quartet `3211/3212/3213/49234` منتخب کرتا ہے۔ تازہ ترین ریلیز نوٹس: [CHANGELOG.md](../CHANGELOG.md)۔ ---

### ریٹریول کی درستگی **coding-agent-life-v1** (اندرونی corpus، sandbox میں دوبارہ قابلِ تولید) | Adapter | P@5 | R@5 | ٹاپ-5 ہِٹ ریٹ | p50 لیٹینسی | |---|---|---|---|---| | **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms | | grep بیس لائن | 0.227 | 0.967 | 15 / 15 | 0 ms | اس corpus کے لیے **P@5 ریاضیاتی حد (ceiling)** پر 100% ٹاپ-5 ہِٹ ریٹ (0.240، scorecard دیکھیں)۔ Hybrid ہر gold سیشن کو ریٹریو کرتا ہے؛ grep multi-session temporal کوئری پر 2 میں سے 1 gold مِس کرتا ہے۔ فائدہ **recall + temporal** کا ہے، مجموعی precision کا نہیں۔ یہ بینچ مارک چھوٹا اور gold-sparse ہے؛ نیچے دیا گیا بڑا LongMemEval-S بہتر فرق دکھاتا ہے۔ مکمل فی-ٹائپ بریک ڈاؤن + تصحیحی نوٹ: [`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 سوالات) | سسٹم | R@5 | R@10 | MRR | |---|---|---|---| | **agentmemory** | **95.2%** | **98.6%** | **88.2%** | | BM25-only فال بیک | 86.2% | 94.6% | 71.5% |

### ٹوکن کی بچت | طریقہ کار | ٹوکنز/سال | لاگت/سال | |---|---|---| | مکمل context پیسٹ کرنا | 19.5M+ | ناممکن (window سے تجاوز) | | LLM-summarized | ~650K | ~$500 | | **agentmemory** | **~170K** | **~$10** | | agentmemory + مقامی embeddings | ~170K | **$0** |

> Embedding ماڈل: `all-MiniLM-L6-v2` (مقامی، مفت، کوئی API key نہیں)۔ مکمل رپورٹس: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md)، [`benchmark/QUALITY.md`](../benchmark/QUALITY.md)، [`benchmark/SCALE.md`](../benchmark/SCALE.md)۔ حریف موازنہ: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) جو agentmemory کا mem0، Letta، Khoj، supermemory، TencentDB Agent Memory، MemPalace، Zep/Graphiti، Cognee، Hippo سے موازنہ کرتا ہے۔ **مقامی طور پر دہرائیں:** [`eval/README.md`](../eval/README.md)، LongMemEval `_s` (عوامی 500-سوالات) + `coding-agent-life-v1` (اندرونی 15-سیشن corpus) کے لیے ایک adapter-pluggable ہارنس۔ Grep / vector / agentmemory adapters ساتھ ساتھ اسکور کرتے ہیں، NDJSON آؤٹ پٹ، شائع شدہ scorecards [`docs/benchmarks/`](../docs/benchmarks/) میں آتے ہیں۔ **[codegraph](https://github.com/colbymchenry/codegraph)، [Understand Anything](https://github.com/Lum1104/Understand-Anything)، اور [Graphify](https://github.com/safishamsi/graphify) کے ساتھ جوڑی بناتا ہے۔** Code-graph انڈیکسنگ، multi-agent build pipelines، اور docs / PDFs / images / videos میں وسیع نالج گرافس۔ agentmemory کام کو یاد رکھتا ہے؛ یہ تین پراجیکٹس باقی context layer کو روشن کرتے ہیں۔ Recipes + سوال-روٹنگ ٹیبل: [`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	بلٹ-اِن (CLAUDE.md)
قسم	میموری انجن + MCP سرور	میموری لیئر API	مکمل ایجنٹ رن ٹائم	ذاتی AI	میموری API + ایپ	ٹیم میموری ہب (LLM پراکسی)	ویکٹر میموری (OSS)	میموری انجن (Oracle DB)	میموری سسٹم	سٹیٹک فائل
ریٹریول R@5	95.2%	68.5% (LoCoMo)	83.2% (LoCoMo)	N/A	خود رپورٹ شدہ	PersonaMem 76% (خود رپورٹ شدہ)	~96.6% (خود رپورٹ شدہ)	94.4% (خود رپورٹ شدہ)	N/A	N/A (grep)
خودکار کیپچر	12 ہکس (کوئی دستی کام نہیں)	دستی `add()` کالز	ایجنٹ خود ترمیم کرتا ہے	دستی	API کی جانب سے استخراج	پراکسی انٹرسیپشن (base-URL سویپ)	دستی	API استخراج	دستی	دستی ترمیم
سرچ	BM25 + ویکٹر + گراف (RRF فیوژن)	ویکٹر + گراف	ویکٹر (آرکائیول)	سیمینٹک	ویکٹر + RAG	4 asset اقسام (Chat / Skill / Wiki / CodeGraph)	صرف ویکٹر	ویکٹر + سیمینٹک	زوال پر مبنی وزن	سب کچھ context میں لوڈ کرتا ہے
ملٹی-ایجنٹ	MCP + REST + لیز + سگنلز	API (کوئی ربط نہیں)	صرف Letta رن ٹائم کے اندر	نہیں	نہیں	ٹیم کردار + مشترک asset	نہیں	صرف محدود دائرہ کار میں	ملٹی-ایجنٹ مشترک	فی-ایجنٹ فائلیں
فریم ورک لاک-اِن	کوئی نہیں (کوئی بھی MCP کلائنٹ)	کوئی نہیں	زیادہ (لازمی طور پر Letta استعمال کرنا ہوگا)	اسٹینڈ الون	کوئی نہیں	ہر model کال کے سامنے پراکسی ہوتی ہے	کوئی نہیں	Oracle Database	کوئی نہیں	فی-ایجنٹ فارمیٹ
خارجی انحصار	کوئی نہیں (SQLite + iii-engine)	Qdrant / pgvector	Postgres + ویکٹر DB	متعدد	مینیجڈ کلاؤڈ	Docker اسٹیک (Core + Hub + Proxy)	ویکٹر اسٹور	Oracle AI Database	کوئی نہیں	کوئی نہیں
میموری لائف سائیکل	4-درجاتی استحکام + زوال + خودکار فراموشی	غیر فعال استخراج	ایجنٹ کے زیرِ انتظام	دستی	خودکار فراموشی	دستی جائزہ؛ auto-routing زیرِ تکمیل	کوئی نہیں	واضح نہیں	زوال + استحکام	دستی تراش
ٹوکن کارکردگی	~1,900 ٹوکنز/سیشن ($10/سال)	integration کے لحاظ سے مختلف	بنیادی میموری context میں	مختلف ہوتا ہے	کلاؤڈ قیمتیں	واضح نہیں	کوئی token بجٹ نہیں	LLM پر مبنی (مختلف ہوتا ہے)	مختلف ہوتا ہے	240 obs پر 22K+ ٹوکنز
ریئل-ٹائم ویور	ہاں (پورٹ 3113)	کلاؤڈ ڈیش بورڈ	کلاؤڈ ڈیش بورڈ	ویب UI	کلاؤڈ ڈیش بورڈ	ہب ویب UI	نہیں	نہیں	نہیں	نہیں
سیلف-ہوسٹڈ	ہاں (ڈیفالٹ)	اختیاری	اختیاری	ہاں	نہیں (صرف کلاؤڈ)	ہاں (Docker)	ہاں	ہاں (Oracle DB)	ہاں	ہاں

_{بینچ مارک نوٹ: صرف agentmemory کا R@5 ہمارا اپنا پیمائش شدہ نتیجہ ہے (LongMemEval-S، benchmark/COMPARISON.md سے دوبارہ قابلِ تولید)۔ mem0 اور Letta کے اعداد و شمار ان کے شائع شدہ LoCoMo نمبرز ہیں (ایک مختلف dataset)؛ MemPalace، supermemory، TencentDB (PersonaMem)، اور oracleagentmemory کے اعداد vendor کے خود رپورٹ شدہ دعوے ہیں جنہیں ہم نے آزادانہ طور پر دوبارہ تولید نہیں کیا (oracleagentmemory کا رن Oracle AI Database کے خلاف GPT-5.5 استعمال کرتا تھا)۔ محض اندازاً موازنے کے لیے ساتھ ساتھ دکھایا گیا ہے، ایک جیسے ڈیٹا پر براہِ راست مقابلہ نہیں۔ Star کی تعداد تخمینی ہے اور وقت کے ساتھ بدلتی رہتی ہے۔} **نئے داخل ہونے والے** جن کے بارے میں جاننا مفید ہے، تفصیلی موازنہ [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) میں: | سسٹم | ⭐ | زاویہ | |--------|---|-------| | Zep / Graphiti | 30K | Temporal نالج گراف؛ شائع شدہ temporal-query نتائج میں سب سے مضبوط (LongMemEval 63.8%)، لیکن گراف asynchronously بنتا ہے لہٰذا تازہ facts تاخیر سے آ سکتے ہیں | | Cognee | 30K | Document-to-knowledge-graph ingestion، صرف Python، structured entity extraction کے لیے بنایا گیا ہے، سیشن کیپچر کے لیے نہیں | ان میں سے کوئی بھی coding-agent hooks سے خودکار کیپچر نہیں کرتا، local-first ویور نہیں دیتا، یا keyless نہیں چلتا — یہ وہی ترکیب ہے جس کے گرد agentmemory تعمیر کیا گیا ہے۔ ---

مطابقت: یہ ریلیز `iii-sdk` 0.22.1 کو ہدف بناتی ہے اور iii-engine v0.22.1 کو pin کرتی ہے۔ ### 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 کی توثیق کریں سرور چلنے کی حالت میں، REST، health، ویور، اور iii پر مبنی رن ٹائم اسٹیٹس کی توثیق کریں: ```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 ``` اسٹارٹ اپ ready پینل تمام چار پورٹس کا حساب رکھتا ہے: 3111 پر REST/MCP HTTP، 3112 پر iii streams، 3113 پر ویور، اور 49134 پر iii ورکر WebSocket۔ `status` agentmemory کی health اور فعال provider/embedding موڈ کی تصدیق کرتا ہے۔ ایک probe محفوظ کریں اور تصدیق کریں کہ وہ تلاش کے قابل ہے: ```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}' ``` پھر `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 connect # wire 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 ``` Import کیے گئے سیشنز نیٹیو سیشنز کے ساتھ Replay picker میں ظاہر ہوتے ہیں۔ پسِ پردہ ہر entry `mem::replay::load`، `mem::replay::sessions`، اور `mem::replay::import-jsonl` iii فنکشنز کے ذریعے روٹ ہوتی ہے، بغیر کسی side-channel سرورز کے۔ ہر import کیا گیا transcript سرچ کے لیے indexed ہوتا ہے، اس پر origin channel `import` کا نشان لگایا جاتا ہے، اور اس سے session crystal اور 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 ``` انتباہ: یہ کمانڈ موجودہ workspace/runtime کو تبدیل کرتی ہے۔ یہ JavaScript dependencies اپ ڈیٹ کر سکتی ہے اور pinned `iiidev/iii:0.22.1` Docker image کھینچ سکتی ہے۔ یہ کبھی بھی کوئی غیر-pinned یا نیا iii engine انسٹال نہیں کرتی۔ عملی تفصیلات `src/cli.ts` میں موجود ہیں (`src/cli.ts:544-595` کے حوالے سے `runUpgrade` دیکھیں)۔ ### Claude Code (ایک بلاک، اسے پیسٹ کریں) ```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. ``` #### 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 ``` یہ انہی hook کمانڈز کو `~/.claude/settings.json` میں ضم کرتا ہے، ان absolute paths کے ساتھ جو currently installed `@agentmemory/agentmemory` پیکیج کی bundled `plugin/` ڈائرکٹری سے resolve ہوتے ہیں۔ paths کو تازہ کرنے کے لیے 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 بھی انسٹال کریں۔

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 the agentmemory repo to ~/.hermes/plugins/agentmemory. ``` مکمل گائیڈ: [`integrations/hermes/`](../integrations/hermes/)

### دیگر ایجنٹس میموری سرور شروع کریں: `npx -y @agentmemory/agentmemory@latest` #### `npx skills add` کے ذریعے نیٹیو اسکلز (50+ ایجنٹس) 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)** ہے: - `agentmemory connect ` MCP سرور کنفیگ لکھتا ہے تاکہ ٹولز دستیاب ہو جائیں۔ - `npx skills add rohitg00/agentmemory` اسکلز انسٹال کرتا ہے تاکہ ایجنٹ کو معلوم ہو کہ انہیں کب کال کرنا ہے۔ ان چند ایجنٹس کے لیے جنہیں 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 لسٹنگ (submission زیرِ جائزہ) یا Cursor Settings → Plugins → local checkout۔ 7 auto-capture ہکس رجسٹر کرتا ہے (sessionStart، beforeSubmitPrompt، preToolUse، postToolUse، postToolUseFailure، stop، sessionEnd) + 17 اسکلز + MCP سرور، جن کے `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` Cursor کے plugin dashboard میں منیج ہوتے ہیں۔ Cursor IDE اور `cursor-agent` CLI دونوں میں کام کرتا ہے؛ CLI کے print-mode prompts سیشن کے اختتام پر session transcript سے backfill ہوتے ہیں۔ | | **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/extensions/agentmemory` | `agentmemory connect pi` bundled extension کو pi کی auto-discovery ڈائرکٹری میں انسٹال کرتا ہے (ایجنٹ شروع ہونے پر recall، ایجنٹ ختم ہونے پر کیپچر، `memory_search` / `memory_save` / `memory_health` ٹولز، `/agentmemory-status`)۔ چلتے ہوئے pi میں `/reload` اسے اٹھا لیتا ہے۔ [`integrations/pi`](../integrations/pi/) ایک pi پیکیج بھی ہے (ایک checkout سے `pi install ./integrations/pi`)۔ | | **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 انسٹال ہونے پر 8 agentmemory اسکلز (`remember`، `recall`، `recap`، `handoff`، `forget`، `commit-context`، `commit-history`، `session-history`) Warp کے slash-command palette میں نیٹیو طور پر ظاہر ہوتی ہیں۔ | | **Cline (CLI)** | `~/.cline/mcp.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` میں ترمیم کرتا ہے۔ **اگر آپ کے پاس پہلے سے `config.yaml` ہے** تو adapter `mcpServers:` کے نیچے پیسٹ کرنے کے لیے عین وہی بلاک پرنٹ کرتا ہے؛ یہ خاموشی سے آپ کی yaml کو دوبارہ نہیں لکھتا کیونکہ comments اور anchors کو محفوظ طریقے سے برقرار رکھنے کے لیے ایک YAML parser درکار ہے جو یہ پیکیج شپ نہیں کرتا۔ Continue `mcpServers` کے لیے array شکل (object نہیں) استعمال کرتا ہے۔ | | **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` home-level patch layer میں ایک `@deepseek-ai/dsh-mcp-client` row شامل کرتا ہے جسے ہر Harness profile لوڈ کرتا ہے؛ tools `mcp__agentmemory__*` کے طور پر رجسٹر ہوتے ہیں۔ auto-capture بھی جوڑنے کے لیے `--with-hooks` پاس کریں: bundled Claude Code hook اسکرپٹس Harness کے first-party `@deepseek-ai/dsh-hooks-claude-code` bridge (SessionStart، UserPromptSubmit، PreToolUse، PostToolUse، Stop) کے ذریعے `$DSH_HOME/agentmemory.hooks.json` میں لکھے گئے ایک manifest سے چلتے ہیں۔ جب `DSH_HOME` سیٹ نہ ہو تو ڈیفالٹ `~/.dsh` ہے۔ | | **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 سے بات کریں: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`۔ | | **کوئی بھی ایجنٹ (32+)** | n/a | `npx skillkit install agentmemory` host کو خودکار طور پر detect کرتا ہے اور ضم کرتا ہے۔ | **Sandboxed MCP کلائنٹس** (Flatpak / Snap / restrictive containers) جو host کے `localhost` تک نہیں پہنچ سکتے: `env` بلاک میں `"AGENTMEMORY_FORCE_PROXY": "1"` بھی سیٹ کریں، اور `AGENTMEMORY_URL` کو کسی ایسے route کی طرف پوائنٹ کریں جہاں sandbox واقعی پہنچ سکے (مثلاً آپ کا LAN IP)۔ ### پروگرامیٹک رسائی (Python / Rust / Node) agentmemory اپنے core operations کو iii فنکشنز کے طور پر رجسٹر کرتا ہے (`mem::remember`، `mem::observe`، `mem::context`، `mem::smart-search`، `mem::forget`)۔ iii SDK رکھنے والی کوئی بھی زبان انہیں براہِ راست `ws://localhost:49134` پر کال کر سکتی ہے، ہر زبان کے لیے علیحدہ REST کلائنٹ کی ضرورت نہیں۔ ```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"}, }) ``` عملی مثال: [`examples/python/`](../examples/python/) (quickstart + observation/recall فلو)۔ iii رن ٹائم کے بغیر hosts کے لیے `:3111` پر REST بدستور دستیاب ہے۔ ### سورس سے ```bash git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory npm install && npm run build && npm start ``` اگر pinned بائنری پہلے سے انسٹال ہے تو یہ agentmemory کو مقامی `iii-engine` کے ساتھ شروع کرتا ہے، یا منتخب ہونے پر Docker Compose استعمال کرتا ہے۔ REST، streams، اور ویور ڈیفالٹ کے طور پر `127.0.0.1` سے bind ہوتے ہیں۔ خودکار macOS/Linux بائنری راستے کو `curl`، ایک POSIX `sh`، اور `tar` درکار ہیں۔ `iii-engine` کو دستی طور پر انسٹال کریں۔ **agentmemory فی الحال `iii-engine` کو `v0.22.1` پر pin کرتا ہے**، یہی وہ ریلیز ہے جو اس کی `iii-sdk` dependency کی بھی ہے؛ ورکر اسی انجن کا wire پروٹوکول بولتا ہے، اور 0.20.0 نے SDK سطح کو دوبارہ ترتیب دیا تھا، لہٰذا یہ دونوں agentmemory ریلیزز میں ساتھ ساتھ چلتے ہیں۔ اگر آپ اپنا انجن چلاتے ہیں اور جانتے ہیں کہ یہ میچ کرتا ہے تو `AGENTMEMORY_III_VERSION=` سے اوور رائیڈ کریں۔ - **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` کو `x86_64-apple-darwin` سے بدلیں - **Linux x64:** `x86_64-unknown-linux-gnu` سے بدلیں - **Linux arm64:** `aarch64-unknown-linux-gnu` سے بدلیں - **Windows:** [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) سے `iii-x86_64-pc-windows-msvc.zip` ڈاؤن لوڈ کریں اور `iii.exe` کو `%USERPROFILE%\.agentmemory\bin\iii.exe` میں ایکسٹریکٹ کریں ہر archive کا release page پر ایک مماثل `.sha256` فائل موجود ہے؛ پلیٹ فارم بدلتے وقت، اوپر دیے گئے چیک میں وہی فائل کا hash استعمال کریں (Windows پر: `Get-FileHash`)۔ `npx @agentmemory/agentmemory` میں خودکار انسٹالر ان hashes کو pin کرتا ہے اور کسی غیر مماثل archive کو مسترد کر دیتا ہے۔ یا Docker استعمال کریں (bundled `docker-compose.yml` `iiidev/iii:0.22.1` کھینچتا ہے)۔ مکمل docs: [iii.dev/docs](https://iii.dev/docs)۔ ### Windows agentmemory Windows 10/11 پر چلتا ہے، لیکن صرف Node.js پیکیج کافی نہیں؛ آپ کو ایک background process کے طور پر pinned iii-engine v0.22.1 رن ٹائم بھی درکار ہے۔ CLI Windows ZIP کو خودکار طور پر ایکسٹریکٹ نہیں کرتا، لہٰذا نیٹیو Windows صارفین کو `iii.exe` دستی طور پر انسٹال کرنا، WSL2 استعمال کرنا، یا Docker Desktop منتخب کرنا ضروری ہے۔ نیٹیو Windows خودکار MCP wiring صرف `agentmemory connect copilot-cli` کو سپورٹ کرتی ہے۔ Claude Code، Codex، Cursor، اور ہر دوسرے نیٹیو Windows ایجنٹ کے لیے، [دیگر ایجنٹس](#other-agents) سے دستی MCP بلاک کو اس ایجنٹ کی Windows کنفیگ میں کاپی کریں۔ WSL میں `connect` چلانا صرف اس وقت مناسب ہے جب target ایجنٹ بھی اسی WSL ماحول میں انسٹال ہو؛ یہ کسی Windows-host ایجنٹ کی کنفیگریشن میں ترمیم نہیں کرتا۔ **آپشن A: prebuilt Windows بائنری (تجویز کردہ)** ```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 ``` **آپشن 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 ``` **آپشن C: صرف اسٹینڈ الون MCP (کوئی انجن نہیں)۔** اگر آپ کو اپنے ایجنٹ کے لیے صرف MCP ٹولز درکار ہیں اور REST API، ویور، یا cron jobs کی ضرورت نہیں، تو انجن کو مکمل طور پر نظرانداز کریں: ```powershell npx -y @agentmemory/agentmemory@latest mcp # or via the shim package: npx -y @agentmemory/mcp ``` **Windows کے لیے Diagnostics:** اگر `npx -y @agentmemory/agentmemory@latest` ناکام ہو جائے، تو اصل انجن stderr دیکھنے کے لیے اسے `--verbose` کے ساتھ دوبارہ چلائیں۔ عام ناکامی کی صورتیں: | علامت | حل | |---|---| | `The engine process started but the REST API never responded.` | تصدیق کریں کہ تمام چار derived پورٹس خالی ہیں، چیک کریں کہ pinned `iii.exe` زندہ رہا، پھر `--verbose` کے ساتھ دوبارہ چلائیں اور captured انجن stderr دیکھیں | | `Could not start iii-engine` | نہ `iii.exe` اور نہ ہی Docker انسٹال ہے۔ اوپر آپشن A یا B دیکھیں | | پورٹ ٹکراؤ (conflict) | کیا bound ہے دیکھنے کے لیے `netstat -ano \| findstr :3111`، پھر اسے kill کریں یا `--port ` استعمال کریں | | Docker انسٹال ہونے کے باوجود Docker fallback چھوڑ دیا گیا | یقینی بنائیں کہ Docker Desktop واقعی چل رہا ہے (system tray آئیکن) | > نوٹ: iii **انجن** ایک prebuilt بائنری ہے، cargo crate نہیں، لہٰذا اسے `cargo install` کرنے کی کوشش نہ کریں۔ (iii **SDKs** crates.io، npm، اور PyPI پر شائع ہوتے ہیں، لیکن agentmemory کو ان کی ضرورت نہیں۔) معاون انجن انسٹال طریقے سب v0.22.1 پر pinned ہیں: اوپر دی گئی prebuilt بائنری، agentmemory کا macOS/Linux auto-install راستہ (`curl`، POSIX `sh`، اور `tar` درکار)، اور Docker image `iiidev/iii:0.22.1`۔ ایک خالی upstream `install.sh | sh` تازہ ترین انجن انسٹال کرتا ہے، جسے agentmemory سپورٹ نہیں کرتا۔ `npx -y @agentmemory/agentmemory@latest` استعمال کریں؛ macOS/Linux پر یہ pinned انجن کو `~/.agentmemory/bin` میں لاتا ہے۔ ---

ڈیپلائی

منظم hosts کے لیے ون-کلک templates۔ ہر ایک ایک self-contained Dockerfile شپ کرتا ہے جو npm سے `@agentmemory/agentmemory` کھینچتا ہے اور سرکاری `iiidev/iii` Docker Hub image سے iii انجن بائنری کاپی کرتا ہے؛ کسی pre-built agentmemory image کی ضرورت نہیں۔ Persistent اسٹوریج `/data` پر mount ہوتا ہے؛ first-boot entrypoint npm-bundled iii کنفیگ (جو `127.0.0.1` سے bind ہوتا ہے) کو ایک deploy-tuned کنفیگ سے overwrite کرتا ہے جو `0.0.0.0` سے bind ہوتا ہے اور absolute `/data` paths استعمال کرتا ہے، HMAC secret تیار کرتا ہے، پھر agentmemory CLI کو exec کرنے سے پہلے `gosu` کے ذریعے `root` سے `node` تک privileges کم کر دیتا ہے۔

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 دونوں آپ کے اپنے۔ صرف پورٹ `3111` publish کی جاتی ہے۔ `3113` پر ویور container کے اندر loopback سے bound رہتا ہے؛ ہر template کا README اس تک پہنچنے کے لیے SSH-tunnel پیٹرن دستاویز کرتا ہے۔ ---

ہر کوڈنگ ایجنٹ سیشن ختم ہوتے ہی سب کچھ بھول جاتا ہے، اور ہر نیا سیشن آپ کے دوبارہ اپنا stack بیان کرنے سے شروع ہوتا ہے۔ agentmemory پسِ منظر میں چلتا ہے اور یہ قدم ختم کر دیتا ہے۔ ```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. ``` ### بلٹ-اِن ایجنٹ میموری کے مقابلے میں ہر AI کوڈنگ ایجنٹ بلٹ-اِن میموری کے ساتھ آتا ہے: Claude Code کے پاس `MEMORY.md` ہے، Cursor کے پاس notepads ہیں، Cline کے پاس memory bank ہے۔ یہ sticky notes کی طرح کام کرتے ہیں۔ agentmemory ان sticky notes کے پیچھے موجود searchable ڈیٹابیس ہے۔ | | بلٹ-اِن (CLAUDE.md) | agentmemory | |---|---|---| | اسکیل | 200-لائن کی حد | لامحدود | | سرچ | سب کچھ context میں لوڈ کرتا ہے | BM25 + ویکٹر + گراف (صرف top-K) | | ٹوکن لاگت | 240 observations پر 22K+ | ~1,900 ٹوکنز (92% کم) | | کراس-ایجنٹ | فی-ایجنٹ فائلیں | MCP + REST (کوئی بھی ایجنٹ) | | کوآرڈینیشن | کوئی نہیں | Leases، سگنلز، actions، routines | | Observability | دستی طور پر فائلیں پڑھنا | :3113 پر ریئل-ٹائم ویور | ---

### میموری 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-درجاتی میموری استحکام (Consolidation) یہ انسانی دماغ کے میموری پراسیس کرنے کے طریقے پر مبنی ہے، بشمول نیند کے دوران ہونے والا consolidation۔ | درجہ | کیا | مثال (Analogy) | |------|------|---------| | **Working** | tool use سے خام observations | قلیل مدتی میموری | | **Episodic** | compressed سیشن خلاصے | "کیا ہوا" | | **Semantic** | نکالے گئے facts اور patterns | "میں کیا جانتا ہوں" | | **Procedural** | Workflows اور فیصلہ سازی کے patterns | "کیسے کرنا ہے" | میموریز وقت کے ساتھ decay ہوتی ہیں (Ebbinghaus curve)۔ بار بار رسائی کی جانے والی میموریز مضبوط ہوتی ہیں۔ Stale میموریز خودکار طور پر evict ہو جاتی ہیں۔ تضادات (contradictions) کو detect اور resolve کیا جاتا ہے۔ ### کیا کیپچر ہوتا ہے | 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 | تفصیل | |---|---| | **خودکار کیپچر** | ہر tool use ہکس کے ذریعے ریکارڈ ہوتا ہے، کوئی دستی کام نہیں | | **سیمینٹک سرچ** | 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 ان کی ہسٹری رکھتی ہے۔ ویکٹرز کریش یا force-kill سے بچ جاتے ہیں۔ ویکٹر index کم از کم ہر `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 منٹ) بعد buckets میں محفوظ ہوتا ہے۔ اس دوران شامل یا ہٹایا گیا ہر ویکٹر state store میں ایک چھوٹے pending log میں فوراً لکھ دیا جاتا ہے، اور اگلا اسٹارٹ اسے embedding provider کو کال کیے بغیر replay کرتا ہے۔ ہر کامیاب save لاگ کو خالی کر دیتا ہے۔ وہ documents جن کا replay کے بعد بھی کوئی ویکٹر نہیں ہوتا انہیں پسِ منظر میں `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) کے batches میں دوبارہ embed کیا جاتا ہے جب تک کوئی باقی نہ رہے، اور رکا ہوا backfill اگلے اسٹارٹ پر جاری رہتا ہے۔ `/agentmemory/status` اور ویور pending log کا سائز اور backfill اسٹیٹس دکھاتے ہیں۔ Keyless انسٹالز کچھ نہیں لکھتے۔ 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` | مفت | پہلے ماڈل ڈاؤن لوڈ کے بعد آن-ڈیوائس، صرف-BM25 کے مقابلے میں +8pp recall | | 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` | $0.02/1M | بہترین کوالٹی | | 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'`)۔ ---

`:3113` پر ویور دکھاتا ہے کہ آپ کے ایجنٹ نے **کیا یاد رکھا**۔ [iii کنسول](https://iii.dev/docs/console) دکھاتا ہے کہ آپ کے ایجنٹ نے **کیا کیا**: ہر میموری op ایک OpenTelemetry trace کے طور پر، ہر KV entry قابلِ ترمیم، ہر فنکشن invocable، ہر stream tap کرنے کے قابل۔ ایک ہی میموری پر دو کھڑکیاں: ایک product-shaped، ایک engine-shaped۔ کسی `memory_smart_search` کو فائر ہوتے دیکھیں اور BM25 scan → embedding lookup → RRF fusion → reranker کو ایک waterfall کے طور پر دیکھیں۔ KV browser میں کسی پھنسے ہوئے consolidation timer میں ترمیم کریں۔ کسی تبدیل شدہ payload کے ساتھ `PostToolUse` hook کو دوبارہ چلائیں (replay)۔ WebSocket stream کو pin کریں اور observations کو لائیو آتے دیکھیں۔ agentmemory یہ مفت فراہم کرتا ہے کیونکہ ہر function call اور trigger iii کے ذریعے فائر ہوتا ہے؛ کچھ بھی custom نہیں، instrument کرنے کے لیے کچھ نہیں۔

iii console کا Workers صفحہ: جڑے ہوئے workers بشمول agentmemory instances، لائیو function counts اور runtime metadata کے ساتھ
Workers صفحہ: ہر جڑا ہوا worker، بشمول agentmemory خود، PID، function count، runtime، اور last-seen کے ساتھ۔

**پہلے سے انسٹال۔** کنسول pinned `iii` انجن (0.22+) کے ساتھ شپ ہوتا ہے؛ علیحدہ سے کچھ بھی انسٹال کرنے کی ضرورت نہیں۔ پہلا لانچ انجن کے ساتھ کنسول بائنری ڈاؤن لوڈ کرتا ہے۔ **agentmemory کے ساتھ لانچ کریں:** ```bash agentmemory console ``` یہ pinned انجن کے `iii console` کو agentmemory کے resolve کردہ پورٹس (REST، streams، bridge) کے خلاف چلاتا ہے اور اسے ویور سے ایک پورٹ اوپر سرو کرتا ہے، ڈیفالٹ کے طور پر `http://localhost:3114`۔ `--console-port N` کوئی اور پورٹ منتخب کرتا ہے؛ `--port` اور `--instance` اسی طرح agentmemory انسٹنس منتخب کرتے ہیں جیسے `stop` کے لیے کرتے ہیں؛ کوئی بھی دوسرا فلیگ آگے پاس ہو جاتا ہے، مثلاً experimental architecture-graph صفحے کے لیے `--enable-flow`۔ وہی کام دستی طور پر، مفید جب `agentmemory` PATH پر نہ ہو: ```bash ~/.agentmemory/bin/iii console --port 3114 \ --engine-port 3111 \ --ws-port 3112 \ --bridge-port 49134 ``` **کنسول سے آپ کیا کر سکتے ہیں:** | صفحہ | استعمال | |------|-----------| | **Workers** | ہر جڑے ہوئے worker اور اس کی لائیو metrics دیکھیں، بشمول agentmemory worker خود۔ | | **Functions** | agentmemory کے کسی بھی فنکشن کو براہِ راست ایک JSON payload کے ساتھ invoke کریں؛ بغیر کسی کلائنٹ جوڑے `memory.recall`، `memory.consolidate`، `graph.query` کو ٹیسٹ کرنے کے لیے مفید۔ | | **Triggers** | HTTP، cron، event، اور state triggers کو دوبارہ چلائیں: consolidation cron کو دستی طور پر فائر کریں، کسی HTTP route کو retry کریں، ایک state تبدیلی emit کریں۔ | | **States** | sessions، memory slots، lifecycle timers، اور embeddings index پر مکمل CRUD والا KV browser؛ قدریں جگہ پر ترمیم کریں۔ | | **Streams** | memory writes، hook events، اور observation اپ ڈیٹس کے لیے لائیو WebSocket مانیٹر جیسے وہ iii streams سے گزرتے ہیں۔ | | **Queues** | Durable queue topics + dead-letter management۔ ناکام embedding / compression jobs کو دوبارہ چلائیں یا drop کریں۔ | | **Traces** | OpenTelemetry waterfall / flame / service-breakdown views۔ `trace_id` سے فلٹر کریں تاکہ عین دیکھا جا سکے کہ کسی ایک `memory.search` نے کون سے functions، DB calls، اور embedding requests پیدا کیے۔ | | **Logs** | trace/span IDs سے فلٹر اور correlated structured OTEL logs۔ | | **Config** | Runtime configuration: دیکھیں کہ آپ کا انجن عین کن workers، providers، اور ports کے ساتھ چل رہا ہے۔ | | **Flow** | (اختیاری، `--enable-flow`) ہر worker، trigger، اور stream کا انٹرایکٹو architecture گراف۔ |

iii console کا trace waterfall view جو فی-span duration دکھاتا ہے
Traces: ہر میموری operation کے لیے waterfall / flame / service breakdown۔

**Traces پہلے سے آن ہیں:** `iii-config.yaml` `iii-observability` worker کو فعال حالت میں شپ کرتا ہے (`exporter: memory`، `sampling_ratio: 0.1`، metrics + logs)۔ کسی اضافی کنفیگ کی ضرورت نہیں؛ جس لمحے agentmemory شروع ہوتا ہے، ہر میموری operation ایک structured log بھیجتا ہے جسے کنسول پڑھ سکتا ہے، اور ان میں سے ہر دسواں (`sampling_ratio: 0.1`) ایک trace span بھی بھیجتا ہے۔ اگر آپ اس کے بجائے Jaeger/Honeycomb/Grafana Tempo کو export کرنا چاہتے ہیں، تو `exporter: memory` کو `exporter: otlp` میں تبدیل کریں اور iii کی observability docs کے مطابق collector اینڈ پوائنٹ سیٹ کریں۔ > **خبردار:** کنسول پر خود کوئی auth نافذ نہیں ہے؛ اسے `127.0.0.1` (ڈیفالٹ) سے bound رکھیں اور کبھی اسے عوامی طور پر ظاہر نہ کریں۔ ---

agentmemory **پہلے سے ہی ایک چلتا ہوا [iii](https://iii.dev) instance ہے**۔ تین primitives (worker، function، trigger) رن ٹائم کو compose کرتے ہیں؛ KV state، streams، اور OTEL traces ان iii-state، iii-stream، اور iii-observability workers سے آتے ہیں جو iii کے ساتھ شپ ہوتے ہیں۔ آپ نے Postgres، Redis، Express، pm2، یا Prometheus انسٹال نہیں کیے، کیونکہ iii انہیں replace کرتا ہے۔ اس کا مطلب ہے کہ صرف ایک اور کمانڈ agentmemory کو ایک مکمل نئی صلاحیت کے ساتھ وسعت دیتی ہے۔ ### agentmemory کو مزید workers کے ساتھ وسعت دیں وہ builtins جن کی agentmemory کو ضرورت ہے پہلے سے `iii-config.yaml` میں ہیں اور اس کے ساتھ boot ہوتے ہیں: `iii-state` (KV)، `iii-queue` (event subscribers کے لیے durable retries)، `iii-pubsub`، `iii-cron`، `iii-stream`، اور `iii-observability` (ہر function پر OTEL traces، metrics اور logs)۔ [iii worker registry](https://workers.iii.dev) سے کوئی اور چیز اسی انجن میں پلگ ہو جاتی ہے: `iii-config.yaml` کو `~/.agentmemory/iii-config.yaml` میں کاپی کریں (CLI bundled فائل کے بجائے اس فائل کو ترجیح دیتا ہے اور پھر بھی اس میں ports اور data paths render کرتا ہے)، entry شامل کریں، `~/.agentmemory/bin/iii update worker` سے ایک بار worker رن ٹائم انسٹال کریں، اور agentmemory دوبارہ شروع کریں۔ ```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 کے ساتھ آپ کو کیا ملتا ہے | |---|---| | [`database`](https://workers.iii.dev/workers/database) | جب آپ in-memory KV ڈیفالٹس سے بڑھ جائیں تو SQL-backed state adapter | | [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | `memory_recall` سے نکلا ہوا کوڈ آپ کے shell کے بجائے ایک throwaway VM کے اندر چلتا ہے | | [`mcp`](https://workers.iii.dev/workers/mcp) | agentmemory کے ساتھ اضافی MCP سرورز کھڑے کریں، وہی انجن شیئر کریں | انجن 0.22.x پر اوپر دیے گئے builtins کے لیے `iii-` prefix والے نام رکھیں؛ بغیر prefix کے `http`، `state`، `queue`، `pubsub` اور `cron` entries وہ standalone registry workers ہیں جن کی طرف agentmemory 0.23 migration کے ساتھ منتقل ہوتا ہے۔ مکمل registry: [workers.iii.dev](https://workers.iii.dev)۔ وہاں موجود ہر worker انہی primitives کے ذریعے compose ہوتا ہے جو agentmemory استعمال کرتا ہے، اور جو agentmemory آپ کے پاس پہلے سے ہے وہ خود انہی میں سے ایک ہے۔ ### Engine کنفیگ اور bind ایڈریس `agentmemory start` انجن کنفیگ کو پہلی موجود فائل سے پڑھتا ہے: `AGENTMEMORY_III_CONFIG`، موجودہ ڈائرکٹری میں `./iii-config.yaml`، `~/.agentmemory/iii-config.yaml`، پھر bundled `iii-config.yaml`۔ ہر اسٹارٹ پر یہ اس فائل (data paths، ports، state backend) کو `~/.agentmemory/data/iii-config.runtime.yaml` میں render کرتا ہے اور انجن کو rendered کاپی کے ساتھ لانچ کرتا ہے، لہٰذا rendered فائل کے بجائے سورس فائل میں ترمیم کریں۔ سورس فائل کی `host:` قدریں جیسی لکھی گئی ہیں ویسی ہی رکھی جاتی ہیں۔ bundled `iii-config.yaml` جانستہ طور پر `127.0.0.1` سے bind ہوتا ہے، اور یہ ڈیفالٹ container کے اندر بھی لاگو ہوتا ہے۔ container میں شروع کیا گیا CLI container کے loopback پر سنتا ہے، لہٰذا published ports کچھ بھی تک نہیں پہنچتے۔ containerized CLI کو published ports کے ذریعے سرو کرنے کے لیے، `AGENTMEMORY_III_CONFIG` کو ایسی کنفیگ پر سیٹ کریں جو `0.0.0.0` سے bind ہو۔ پیکیجڈ `iii-config.docker.yaml` ایک ایسی ہی مثال ہے: یہ `iii-http`، `iii-stream` اور انجن پورٹ کو `0.0.0.0` سے bind کرتی ہے اور state کو `/data` کے تحت محفوظ کرتی ہے، لہٰذا وہاں ایک قابلِ تحریر volume mount کریں۔ `AGENTMEMORY_SECRET` سیٹ رکھیں، اور صرف وہی ports publish کریں جن کی ضرورت ہے، `127.0.0.1` پر یا کسی قابلِ اعتماد پراکسی کے پیچھے۔ اس repo کی `docker-compose.yml` CLI کی config lookup سے نہیں گزرتی: یہ `iii-config.docker.yaml` کو `/app/config.yaml` پر mount کرتی ہے، اور `iii-engine` container `--config /app/config.yaml` کے ساتھ شروع ہوتا ہے۔ ون-کلک [deploy templates](../deploy/) اپنے entrypoints میں اپنی `0.0.0.0` کنفیگ لکھتے ہیں۔ ### اسٹوریج backend: file (ڈیفالٹ) بمقابلہ redis `iii-state` اور `iii-stream` ڈیفالٹ کے طور پر iii-engine کے bundled file-based KV store پر چلتے ہیں: فی scope ایک JSON فائل، جو انجن process کی میموری میں رکھی جاتی ہے اور ٹائمر پر ڈسک پر دوبارہ لکھی جاتی ہے۔ یہ ایک single-user مقامی انسٹال کے لیے درست ڈیفالٹ ہے؛ کئی concurrent writers والا shared daemon اس کے بجائے Redis سے حقیقی فی-key writes حاصل کرتا ہے، فی operation ایک نیٹ ورک round trip کی قیمت پر (ہر `state::*` call اب بھی ایک Redis کنکشن پر serialize ہوتی ہے، لہٰذا یہ file store کے lock کو ایک socket سے بدلتا ہے، parallelism سے نہیں)۔ دونوں workers کو iii-engine کے built-in `redis` adapter پر سوئچ کرنے کے لیے `AGENTMEMORY_STATE_BACKEND=redis` (نیز `AGENTMEMORY_REDIS_URL`) سیٹ کریں، جو ہر key کو ہر write پر پورے scope کو دوبارہ لکھنے کے بجائے ایک Redis hash field (`HSET`) کے طور پر محفوظ کرتا ہے: ```env # ~/.agentmemory/.env AGENTMEMORY_STATE_BACKEND=redis AGENTMEMORY_REDIS_URL=redis://localhost:6379 ``` `AGENTMEMORY_STATE_BACKEND` ڈیفالٹ کے طور پر `file` ہے؛ اسے سیٹ نہ کرنا آج کے رویے کو بدستور رکھتا ہے، اور کوئی غیر تسلیم شدہ قدر (`file` یا `redis` کے سوا کچھ بھی) خاموش fallback کے بجائے ایک startup error ہے۔ `/agentmemory/status` اور ویور کا Health صفحہ (State store row) رپورٹ کرتے ہیں کہ کون سا backend فعال ہے اور کیا یہ جواب دیتا ہے، کبھی URL نہیں۔ **صرف سادہ `redis://`۔** pinned انجن (0.22.1) اپنا Redis کلائنٹ بغیر TLS سپورٹ کے بناتا ہے، لہٰذا ایک `rediss://` URL (زیادہ تر managed Redis پیشکشیں، جیسے Upstash، Redis Cloud، اور in-transit encryption کے ساتھ ElastiCache، ڈیفالٹ کے طور پر TLS-only ہیں) کنکٹ کرنے میں ناکام رہتا ہے۔ کنکشن غیر مُرمَّز (unencrypted) ہے، لہٰذا Redis پاس ورڈ اور ہر محفوظ شدہ میموری wire پر صاف متن میں گزرتی ہے: کسی مقامی Redis یا کسی قابلِ اعتماد private network پر موجود Redis کی طرف اشارہ کریں۔ کسی اور Redis کے لیے، agentmemory host پر ایک encrypted tunnel چلائیں (stunnel، SSH، یا ایک VPN)، تاکہ سادہ `redis://` hop اسی host پر رہے اور tunnel کا upstream کنکشن encrypted اور authenticated ہو۔ اگر Redis پاس ورڈ میں ایک single quote ہو، تو اسے percent-encode کریں (`%27`)؛ انجن parsing سے پہلے URL کو اپنی YAML کنفیگ میں expand کرتا ہے۔ **فی `--instance` ایک Redis سرور۔** انجن کے Redis key prefixes (`state:`، `stream::`) fixed ہیں، لہٰذا ایک ہی database کی طرف اشارہ کرنے والے دو agentmemory instances (`--instance 1`، `--instance 2`، ...) ایک دوسرے کا ڈیٹا overwrite کر دیتے ہیں۔ ایک علیحدہ database index (`redis://localhost:6379/1`) محفوظ شدہ ڈیٹا کو الگ رکھتا ہے، لیکن انجن لائیو ویور events کو ایک Redis pub/sub چینل (`stream::events`) پر relay کرتا ہے، اور Redis pub/sub database index کو نظرانداز کرتا ہے، لہٰذا ہر instance کا ویور پھر بھی دوسرے کے لائیو events دکھائے گا۔ جب آپ ایک سے زیادہ چلائیں تو ہر instance کو اس کا اپنا Redis سرور (یا پورٹ) دیں۔ **کیا ایک جیسا رہتا ہے، اور کیا فرق ہے۔** Redis پر agentmemory کی ہر خصوصیت کام کرتی ہے: sessions، observations، memories (remember، supersede، evolve، forget)، سرچ اور index buckets، lessons، گراف، audit log اور اس کے monthly scopes، export اور import، governance deletes، consolidation status، ویور snapshot اور اس کا لائیو stream، اور health monitor۔ انجن ہر scope کو ایک Redis hash (`HSET`/`HGET`/`HGETALL`) کے طور پر محفوظ کرتا ہے اور file store جیسے ہی state triggers فائر کرتا ہے۔ تین انجن فرق agentmemory کے اندر ہینڈل ہوتے ہیں: - Redis کسی scope کے records کو کسی fixed ترتیب میں واپس نہیں کرتا۔ agentmemory انہیں سب سے پرانے کو پہلے کی ترتیب میں sort کرتا ہے (record id میں creation time کے لحاظ سے، پھر اس کے timestamp سے) تاکہ lists، paging اور export chunks وہی ترتیب واپس لائیں جو file store پر ہوتی ہے۔ - انجن Redis پر partial updates ایک Lua script میں لاگو کرتا ہے جو خالی arrays کو خالی objects میں بدل دیتا ہے۔ agentmemory خود یہ updates (پڑھنا، تبدیل کرنا، فی-key lock کے تحت لکھنا) Redis پر لاگو کرتا ہے، تاکہ `tags: []` جیسے fields arrays ہی رہیں۔ - Legacy audit log چیک ڈسک پر file store کی فائل تلاش کرنے کے بجائے Redis سے پرانا scope پڑھتا ہے۔ ایک فرق آپ کی توجہ مانگتا ہے: **Redis ریسٹارٹ ہونے کے بعد، انجن ویور کو لائیو events relay کرنا بند کر دیتا ہے** جب تک agentmemory ریسٹارٹ نہ ہو۔ ڈیٹا بدستور نارمل طریقے سے محفوظ اور پڑھا جاتا ہے۔ health monitor ہر 30 سیکنڈ بعد Redis کے ذریعے ایک test event بھیجتا ہے؛ جب یہ واپس نہیں آتا، `/agentmemory/status` اور ویور کا Health صفحہ "Live updates are not reaching the viewer" دکھاتے ہیں ساتھ حل کے: agentmemory ریسٹارٹ کریں۔ اگر Redis بند ہو، تو status رپورٹ "The state store is not answering" دکھاتی ہے اور یہ چیک کرنے کا طریقہ (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`)۔ ایک بہت بڑے scope کی listing پوری hash کو ایک `HGETALL` میں پڑھتی ہے، وہی لاگت جو file store کو اسے میموری میں رکھنے کی ہوتی ہے۔ **تجویز کردہ Redis سیٹنگز۔** ڈیفالٹ `save 3600 1 300 100 60 10000` snapshot پالیسی کسی crash پر منٹوں کی writes کھو سکتی ہے، جو file store کی 5 سیکنڈ flush window سے بھی بدتر ہے۔ جس بھی چیز کا کھونا آپ کو ناپسند ہو اس کے لیے `appendonly yes` سیٹ کریں۔ `maxmemory-policy noeviction` سیٹ کریں؛ `allkeys-lru` یا اس جیسی پالیسیاں Redis کی memory limit تک پہنچنے پر خاموشی سے میموریز گرا دیتی ہیں۔ ایک نیٹیو (غیر-Docker) اسٹارٹ، اور ہر ون-کلک [deploy template](../deploy/) (وہ bundled `iii-config.yaml` کو overwrite کرتے ہیں اور نیٹیو طور پر شروع ہوتے ہیں)، `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` پڑھتے ہیں اور انہیں launch شدہ `iii-config` میں render کرتے ہیں۔ URL خود کبھی اس rendered فائل میں نہیں لکھا جاتا، صرف ایک `${AGENTMEMORY_REDIS_URL}` reference جسے انجن process بوٹ کے وقت اپنے ماحول سے expand کرتا ہے۔ صرف اس repo کا اپنا Docker Compose راستہ (`AGENTMEMORY_USE_DOCKER=1`، یا اسی طرح شروع کیے گئے انجن کو دوبارہ شروع کرنا) `iii-config.docker.yaml` کو read-only mount کرتا ہے اور کبھی render نہیں کرتا؛ `agentmemory start` اس combination کا پتہ چلنے پر خبردار کرتا ہے۔ اس فائل کو دستی طور پر بدلیں، [iii-state](https://workers.iii.dev/workers/iii-state) اور [iii-stream](https://workers.iii.dev/workers/iii-stream) worker docs میں دکھائی گئی وہی `name: redis` / `config: redis_url: ...` شکل کی پیروی کرتے ہوئے، اور `redis_url` کو container سے قابلِ رسائی کسی Redis کی طرف پوائنٹ کریں۔ `docker-compose.yml` انجن container میں `AGENTMEMORY_REDIS_URL` پاس کرتی ہے، لہٰذا `redis_url: '${AGENTMEMORY_REDIS_URL}'` وہاں کام کرتا ہے اور URL کو mounted فائل سے باہر رکھتا ہے۔ Rendered کنفیگ URL کو `~/.agentmemory/data/iii-config.runtime.yaml` سے باہر رکھتی ہے، لیکن انجن کا اپنا configuration worker بوٹ ہونے کے بعد بھی *expanded* قدر کو `~/.agentmemory/config/iii-state.yaml` اور `iii-stream.yaml` میں persist کرتا ہے (iii-engine کی `${VAR}` expansion اس worker کے اپنا seed محفوظ کرنے سے پہلے ہوتی ہے، اور یہ resolved قدر محفوظ کرتا ہے، reference نہیں)۔ اس ڈائرکٹری کو credential رکھنے والی سمجھیں: کسی بھی shared host پر `chmod 700 ~/.agentmemory` کریں، اور database کی admin credentials کے بجائے agentmemory کی ضرورت کے مطابق scoped ایک Redis ACL صارف کو ترجیح دیں۔ **Migration خودکار نہیں ہے۔** `AGENTMEMORY_STATE_BACKEND` بدلنا دونوں طرف ایک خالی store سے شروع ہوتا ہے؛ کوئی چیز موجودہ ڈیٹا کو file سے Redis یا واپس کاپی نہیں کرتی۔ جس backend کو آپ چھوڑ رہے ہیں اس سے export کریں اور جس کی طرف جا رہے ہیں اس میں import کریں۔ یہ bash اور zsh کے تحت یکساں طور پر چلتا ہے (بشمول `bash -u`)۔ `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` جیسا ایک array نہیں چلتا: zsh ہیڈر کو ایک malformed لفظ کے طور پر رکھتا ہے جہاں bash اسے دو میں تقسیم کرتا ہے، لہٰذا جب بھی `AGENTMEMORY_SECRET` سیٹ ہو تو دونوں درخواستیں 401 دیتی ہیں: ```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` کئی calls میں ایک بڑے corpus کو chunk کرنے کے لیے `?maxSessions=` اور `?offset=` بھی قبول کرتا ہے؛ import پر `strategy` یا تو `merge` (default-safe)، `replace`، یا `skip` ہے۔ ### iii کیا replace کرتا ہے | روایتی اسٹیک | agentmemory استعمال کرتا ہے | |---|---| | Express.js / Fastify | iii HTTP Triggers | | SQLite / Postgres + pgvector | iii KV State + in-memory vector index | | SSE / Socket.io | iii Streams (WebSocket) | | pm2 / systemd | iii engine worker supervision | | Prometheus / Grafana | iii OTEL + health monitor | | کسٹم plugin سسٹمز | `iii worker add ` | **219 سورس فائلز · ~52,000 لائنز کوڈ · 2,500+ ٹیسٹس · 311 فنکشنز · 60 KV اسکوپس**، سب تین primitives پر۔ کوئی `agentmemory plugin install` نہیں۔ plugin سسٹم خود iii ہی ہے۔ ---

### 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 شامل کر سکتا ہے۔ ### لاگت سے آگاہ ماڈل انتخاب جب provider اور `AGENTMEMORY_AUTO_COMPRESS=true` دونوں کے ساتھ LLM کی تحریر کردہ background compression فعال ہو، تو یہ ہر observation پر چلتی ہے، لہٰذا ماڈل کا انتخاب ماہانہ خرچ کو نمایاں طور پر بدل دیتا ہے۔ ریکارڈ شدہ workload ڈیٹا: 635 requests / 888K ٹوکنز / 35 گھنٹے فعال استعمال، 2026-05-23 کی قیمتوں پر تین OpenRouter ماڈلز کے خلاف چلایا گیا۔ | ٹیئر | ماڈل | Input / 1M | Output / 1M | ریکارڈ شدہ 35h کی لاگت | نوٹس | |------|-------|------------|-------------|---------------------------|-------| | تجویز کردہ | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (تخمینی) | تازہ ترین DeepSeek؛ compression workloads کے لیے سب سے سستا تجویز کردہ انتخاب۔ | | تجویز کردہ | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Sonnet سے ~10× کم لاگت پر مستحکم compression + summarization کوالٹی۔ | | تجویز کردہ | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | اگر آپ کے سیشنز شدید code-shaped ہیں تو مضبوط code reasoning۔ | | Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (تخمینی) | پیمائش شدہ Sonnet 4.6 رن جیسی فہرستی قیمت؛ 2026-08-31 تک $2/$10 intro قیمت۔ | | Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (تخمینی) | فلیگ شپ ٹیئر؛ ہمیشہ-آن background کام کے لیے مہنگا۔ | | گریز کریں | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (تخمینی) | فلیگ شپ-کلاس ماڈل؛ compression کے لیے overspend۔ | پیمائش شدہ rows ریکارڈ شدہ رن سے آتے ہیں؛ (تخمینی) rows وہی token mix کو ہر ماڈل کی فہرستی قیمت کے مطابق scale کرتے ہیں۔ جب `OPENROUTER_MODEL` کسی premium-tier پیٹرن سے میچ کرتا ہے تو agentmemory ایک runtime warning پرنٹ کرتا ہے۔ ایک بار باخبر انتخاب کرنے کے بعد خاموش کرنے کے لیے `AGENTMEMORY_SUPPRESS_COST_WARNING=1` سیٹ کریں۔ میموری کام کے لیے کوالٹی بمقابلہ لاگت tradeoff: compression ایک summarization task ہے جس کے quality bars نسبتاً نرم ہیں (summary کو ایجنٹ دوبارہ پڑھتا ہے، صارف نہیں)۔ DeepSeek V4 Flash / V4 Pro / Qwen3-Coder اس task پر Sonnet کے rounding error کے اندر رہتے ہیں جبکہ 10-70× کم لاگت پر۔ Premium-tier ماڈلز ان کوئریز کے لیے بچائیں جو آپ خود براہِ راست پڑھتے ہیں۔ ذرائع: [Claude Sonnet 5 کے لیے OpenRouter قیمت](https://openrouter.ai/anthropic/claude-sonnet-5)، [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731)، [DeepSeek قیمت نوٹس](https://api-docs.deepseek.com/quick_start/pricing/)۔ ### ملٹی-ایجنٹ میموری (`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 رویہ، کوئی ٹیگز نہیں، کوئی فلٹرز نہیں)۔ ### پورٹس agentmemory + iii-engine ڈیفالٹ کے طور پر چار پورٹس سے bind ہوتے ہیں۔ اگر ریسٹارٹ `port in use` کے ساتھ ناکام ہو، تو یہ ٹیبل بتاتا ہے کہ کون سا process تلاش کرنا ہے۔ | پورٹ | Process | مقصد | Env override | |------|---------|---------|--------------| | `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` | | `3112` | iii-engine | اندرونی streams worker (agentmemory + ویور کے ذریعے استعمال ہوتا ہے) | `III_STREAM_PORT` (ترجیحی) یا legacy `III_STREAMS_PORT` | | `3113` | agentmemory | ریئل-ٹائم ویور (`http://localhost:3113`) | رپورٹ شدہ URL کے لیے `III_VIEWER_PORT` یا `AGENTMEMORY_VIEWER_URL` | | `49134` | iii-engine | WebSocket؛ workers یہاں رجسٹر ہوتے ہیں، OTel telemetry اسی سے گزرتی ہے | `III_ENGINE_PORT` یا `III_ENGINE_URL` | `--port ` REST anchor کو تبدیل کرتا ہے اور صرف وہاں streams `N+1`، ویور `N+2`، اور انجن WebSocket `N+46023` نکالتا ہے جہاں اوپر دیا گیا متعلقہ واضح پورٹ یا URL سیٹ نہ ہو۔ یہ کوئی isolated lifecycle namespace نہیں بناتا۔ دوسرے daemon کے لیے `--instance 1` استعمال کریں؛ یہ anchor 3211 استعمال کرتا ہے، ڈیفالٹ کے طور پر `3211/3212/3213/49234`، اور ایک علیحدہ `instance-1` data اور lifecycle ڈائرکٹری حاصل کرتا ہے۔ Instances 1 سے 50 تک وہی پیٹرن فالو کرتے ہیں۔ pinned انجن `--no-update-check` کے ساتھ شروع ہوتا ہے (بوٹ پر GitHub کے خلاف کوئی update یا security-advisory lookups نہیں) اور iii کی anonymous usage telemetry بند کے ساتھ: agentmemory اس انجن کے لیے جسے وہ spawn کرتا ہے `III_TELEMETRY_ENABLED=false` سیٹ کرتا ہے جب تک آپ خود یہ variable export نہ کریں، اور bundled compose فائل بھی وہی کرتی ہے۔ جب کسی crashed رن کے بعد ports bound رہ جائیں تو stale-process cleanup: ```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 نیٹیو shutdown پر worker اور انجن pidfile دونوں کو صاف طریقے سے reap کرتا ہے۔ Docker موڈ میں یہ نیٹیو worker کو flush کرتا ہے، عین validated انجن container کو روکتا ہے، اور lossless ریسٹارٹ کے لیے container اور اس کے `/data` mount دونوں کو محفوظ رکھتا ہے؛ اگلا اسٹارٹ اسی container کی توثیق کرتا ہے اور اسے دوبارہ شروع کرتا ہے۔ Docker-backed uninstall کو `agentmemory remove --keep-data` درکار ہے: یہ validated container، اس کے data mount، اور انہیں بحال کرنے کے لیے درکار lifecycle record کو محفوظ رکھتے ہوئے shared agentmemory-managed فائلیں ہٹاتا ہے۔ Destructive Docker ڈیٹا ڈیلیشن جانستہ طور پر backup کے بعد آپریٹر پر چھوڑا جاتا ہے۔ CLI Docker یا VM port holders (Docker backend، vpnkit، colima) کو نیٹیو انجن کے طور پر اپنانے یا signal کرنے سے بھی انکار کرتا ہے جب تک `--force` پاس نہ ہو۔ اوپر دیا گیا دستی cleanup صرف اس post-crash صورت کے لیے ہے جہاں کوئی pidfile پیچھے نہ رہا ہو۔ ### کنفیگ فائل ہر shell میں variables export کرنے کے بجائے agentmemory رن ٹائم کنفیگریشن `~/.agentmemory/.env` میں رکھیں۔ اگر ویور `export ANTHROPIC_API_KEY=...` جیسا کوئی سیٹ اپ اشارہ دکھاتا ہے، تو اسے `export` prefix کے بغیر `ANTHROPIC_API_KEY=...` کے طور پر اس فائل میں کاپی کریں، پھر agentmemory ریسٹارٹ کریں۔ Process ماحولیاتی variables بدستور کام کرتے ہیں اور فائل کی قدروں پر فوقیت رکھتے ہیں۔ Windows پر، وہی فائل `%USERPROFILE%\.agentmemory\.env` پر موجود ہے: ```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 # 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` پر 138 اینڈ پوائنٹس۔ REST API ڈیفالٹ کے طور پر `127.0.0.1` سے bind ہوتا ہے۔ محفوظ اینڈ پوائنٹس کو `Authorization: Bearer ` درکار ہے، اور mesh sync اینڈ پوائنٹس کو دونوں peers پر واضح طور پر سیٹ کیا گیا `AGENTMEMORY_SECRET` درکار ہے۔ **Authentication ڈیفالٹ کے طور پر آن ہے۔** جب `AGENTMEMORY_SECRET` سیٹ نہ ہو (shell میں یا `~/.agentmemory/.env` میں)، سرور پہلے اسٹارٹ پر ایک random secret تیار کرتا ہے اور اسے `0600` موڈ کے ساتھ `~/.agentmemory/secret` میں محفوظ کرتا ہے۔ ہر bundled کلائنٹ جب کسی مقامی سرور سے بات کرتا ہے تو اسے وہاں سے پڑھتا ہے: CLI، ویور، `plugin/scripts` کے تحت ہکس، MCP سرور اور `@agentmemory/mcp` shim، `agentmemory connect` کی لکھی گئی configs، اور bundled OpenCode، Pi، OpenClaw، Hermes اور filesystem-watcher integrations۔ محفوظ شدہ secret صرف loopback URLs (`localhost`، `127.0.0.0/8`، `::1`) کو بھیجا جاتا ہے۔ ایک واضح `AGENTMEMORY_SECRET` ہمیشہ جیتتا ہے، اور ریموٹ کلائنٹس کو بھی اسے سیٹ کرنا ضروری ہے۔ Docker اور `deploy/` entrypoints پہلے سے اپنا secret تیار اور export کرتے ہیں۔ API کو دستی طور پر کال کرنے کے لیے: ```bash curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" 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 | مکمل اینڈ پوائنٹ فہرست: [`src/triggers/api.ts`](../src/triggers/api.ts)

**کیپچر ڈیلیوری۔** 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 کرنا۔** ہر نالج گراف node اور edge ان 32 تازہ ترین observations کے ids رکھتی ہے جہاں سے وہ آئی۔ اس cap سے پہلے لکھے گئے stores فی hot node ہزاروں ids رکھ سکتے ہیں، جو graph سرچ اور ویور کو سست کر دیتا ہے یا worker کو گرا دیتا ہے۔ agentmemory اسے خود ٹھیک کرتا ہے: اپ گریڈ کے بعد پہلے اسٹارٹ پر یہ ہر node، edge، سپرسیڈ شدہ edge (temporal graph ہسٹری) اور cached snapshot کو پسِ منظر میں cap تک trim کرتا ہے، چھوٹے slices میں ان کے درمیان وقفے کے ساتھ، تاکہ سرچ، کیپچر اور ویور کام کرتے رہیں۔ یہ اپنی پیش رفت محفوظ کرتا ہے، ریسٹارٹ کے بعد جاری رہتا ہے اور ختم ہونے کے بعد دوبارہ کبھی نہیں چلتا۔ `/agentmemory/status` اور ویور کا Health صفحہ اسے pending، running (موجودہ scope اور position کے ساتھ)، done یا failed کے طور پر دکھاتے ہیں۔ اسے بند کرنے کے لیے `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` سیٹ کریں۔ اسے دستی طور پر چلانے کے لیے، `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 "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 "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) ``` **ضروریات:** Node.js >= 20 npm/npx کے ساتھ؛ [iii-engine](https://iii.dev/docs) v0.22.1 یا Docker۔ خودکار macOS/Linux انجن انسٹال کو `curl`، ایک POSIX `sh`، اور `tar` بھی درکار ہیں؛ نیٹیو Windows دستی pinned `iii.exe`، WSL2، یا Docker Desktop استعمال کرتا ہے۔

[Apache-2.0](../LICENSE)