סוכן הקוד שלך זוכר הכול. אין יותר הסברים חזרתיים.
בנוי על מנוע iii
זיכרון מתמשך עבור Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, וכל לקוח MCP.
---
## התקנה
דרישות:
- Node.js 20 ואילך עם npm ו-npx (`node -v`, `npm -v`, ו-`npx -v`).
- התקנה אוטומטית של iii-engine ב-macOS/Linux דורשת גם `curl`, מעטפת `sh` תואמת POSIX, ו-`tar`. תמונות מינימליות כמו `node:20-slim` לא בהכרח כוללות אותן.
- Windows מקורי מחייב התקנה ידנית של `iii.exe` בגרסה הנעוצה v0.22.1 של iii-engine. WSL2 או Docker Desktop הם המסלולים הנתמכים האחרים.
פקודת ההתקנה הראשונית הקנונית:
```bash
npx -y @agentmemory/agentmemory@latest
```
ההרצה הראשונה היא הגדרה אינטראקטיבית: בוחרים את הסוכנים לחיווט (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), בוחרים ספק LLM או נשארים ללא מפתח, והיא מזרעת את התצורה, מפעילה את שרת הזיכרון ואת iii-engine הנעוץ שלו, ומציעה להתקין גלובלית כך שהפקודה החשופה `agentmemory` תעבוד בכל מקום לאחר מכן. הדגל `-y` מאשר את הבקשה של npx להתקין את החבילה, ו-`@latest` מונע שימוש בגרסה ישנה שמורה במטמון. ספק מאפשר יכולות LLM, אך דחיסת תצפיות בכתיבת LLM מתחילה רק כש-`AGENTMEMORY_AUTO_COMPRESS=true` מוגדר גם כן.
מצב ללא מפתח (keyless) משבית embeddings וקטוריים. `memory_recall` (נתיב `mem::search`) משתמש ב-BM25, בעוד ש-`memory_smart_search` יכול גם לשלב התאמות מבניות מגרף כשנתוני גרף קיימים כבר. לשליפה סמנטית חינמית במכשיר עצמו, יש להגדיר `EMBEDDING_PROVIDER=local` בקובץ `~/.agentmemory/.env` ולהפעיל מחדש. בקשת ה-embedding הראשונה מורידה את `Xenova/all-MiniLM-L6-v2`; לאחר ההורדה הראשונית, ההסקה רצה מקומית.
סביבת ההרצה המקומית משתמשת בארבעה פורטים: `3111` עבור REST/MCP HTTP, `3112` עבור זרמי iii, `3113` עבור המציג, ו-`49134` עבור ה-WebSocket של worker ה-iii. מצב ה-iii המתמשך חי ב-`~/Library/Application Support/agentmemory` ב-macOS, ב-`$XDG_DATA_HOME/agentmemory` או `~/.local/share/agentmemory` ב-Linux, וב-`%APPDATA%\agentmemory` ב-Windows. יש להשתמש ב-`--data-dir ` או ב-`AGENTMEMORY_DATA_DIR` כדי לשנות זאת, ולהשתמש באותו ערך בכל הפעלה מחדש. לשם תאימות לאחור, `./data/state_store.db` או `./data/iii-config.yaml` קיימים מקבלים עדיפות על פני ברירת המחדל של הפלטפורמה עבור instance 0; דגל מפורש או override של משתנה סביבה עדיין גובר.
לאחר מכן, הדגימו ששליפה עובדת ותנו לסוכן שלכם את ה-skills שלו:
```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 מתאמים מופיעים ברשימה ב[עובד עם כל סוכן](#works-with-every-agent). מדריך הפקודות המלא נמצא ב[התחלה מהירה](#quick-start).
Windows
המסלול המהיר הוא WSL2. הגדרת מנוע ב-Windows מקורי דורשת הורדה של קובץ ה-ZIP הנעוץ v0.22.1 וחילוץ `iii.exe` באופן ידני; ה-CLI לא מחלץ אותו אוטומטית. Docker Desktop נתמך גם הוא. ראו את [הערות Windows](#windows) לפירוט שלב-אחר-שלב.
התקנה גלובלית / EACCES
```bash
npm install -g @agentmemory/agentmemory@latest
```
פקודת ה-npx שלמעלה נשארת מסלול ההתקנה הראשונית הקנוני ומונעת בעיות הרשאה של global-prefix.
npx מגיש גרסה ישנה
npx שומר במטמון לפי גרסה. אפשר לכפות את הגרסה העדכנית עם `npx -y @agentmemory/agentmemory@latest`, או לנקות את המטמון פעם אחת עם `rm -rf ~/.npm/_npx` (macOS/Linux; ב-Windows מוחקים את `%LOCALAPPDATA%\npm-cache\_npx`).
כבר מריצים iii engine משלכם
agentmemory נעוץ לגרסה v0.22.1 של iii-engine ולא יתחבר לגרסה אחרת (ה-worker לא יודע לדבר בפרוטוקול של מנוע אחר). עצרו את המנוע האחר, ואז הריצו `npx -y @agentmemory/agentmemory@latest`. זה מתקין ומריץ את הגרסה הנעוצה v0.22.1 בתוך `~/.agentmemory/bin`, מבלי לגעת ב-`iii` שלכם.
---
agentmemory עובד עם כל סוכן שתומך ב-hooks, ב-MCP, או ב-REST API. כל הסוכנים חולקים את אותו שרת זיכרון.
Claude Code plugin מובנה + 12 hooks + MCP
Codex CLI plugin מובנה + 6 hooks + MCP
GitHub Copilot CLI MCP + hooks/skills של plugin
Cursor plugin מובנה + 7 hooks + MCP
OpenCode plugin ללכידה + MCP
Devin 6 hooks + skills + MCP
OpenClaw plugin מובנה + MCP
Hermes plugin מובנה + MCP
pi plugin מובנה + MCP
OpenHuman backend מובנה מבוסס Memory trait
Gemini CLI שרת MCP
Antigravity MCP + hooks
Claude Desktop שרת MCP
Warp חיבור + MCP + skills
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. שרת אחד, זיכרונות משותפים בין כולם.
---
אתם מסבירים את אותה הארכיטקטורה בכל session מחדש. אתם מגלים מחדש את אותן תקלות. אתם מלמדים מחדש את אותן ההעדפות. הזיכרון המובנה (CLAUDE.md, .cursorrules) מוגבל ל-200 שורות והולך ומתיישן. agentmemory פותר את זה. הוא לוכד בשקט את מה שהסוכן שלכם עושה, דוחס את זה לזיכרון שניתן לחפש בו, ומזריק את ההקשר הנכון כשה-session הבא מתחיל. פקודה אחת. עובד בין סוכנים שונים.
**מה משתנה:** ב-session הראשון הגדרתם JWT auth. ב-session השני אתם מבקשים rate limiting. הסוכן כבר יודע שה-auth שלכם משתמש ב-jose middleware בקובץ `src/middleware/auth.ts`, שהבדיקות שלכם מכסות אימות token, ושבחרתם ב-jose על פני jsonwebtoken בשביל תאימות ל-Edge, בלי להסביר מחדש ובלי copy-paste.
```bash
npx -y @agentmemory/agentmemory@latest
```
כברירת מחדל, agentmemory שומר את מצב ה-iii-engine מחוץ ל-repository שממנו הפעלתם אותו: `~/Library/Application Support/agentmemory` ב-macOS, `$XDG_DATA_HOME/agentmemory` או `~/.local/share/agentmemory` ב-Linux, ו-`%APPDATA%\agentmemory` ב-Windows. `./data/state_store.db` או `./data/iii-config.yaml` legacy קיימים מקבלים שימוש חוזר עבור instance 0 לפני ברירת המחדל של הפלטפורמה. כדי לבחור מיקום באופן מפורש, יש להעביר `--data-dir ` או להגדיר `AGENTMEMORY_DATA_DIR`; כל הגדרה מפורשת גוברת על הגילוי ה-legacy:
```bash
npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
```
הפעלות native ו-Docker משתמשות באותה תיקיית host שנפתרה; Docker עושה לה bind-mount בתוך `/data`. `--instance 1` מוסיף `instance-1` לתיקייה שנפתרה ובוחר ברביעיית הפורטים הנפרדת שבברירת המחדל `3211/3212/3213/49234`.
הערות השחרור העדכניות: [CHANGELOG.md](../CHANGELOG.md).
---
### דיוק שליפה
**coding-agent-life-v1** (קורפוס פנימי, שניתן לשכפול ב-sandbox)
| מתאם | P@5 | R@5 | שיעור פגיעה ב-Top-5 | latency p50 |
|---|---|---|---|---|
| **agentmemory היברידי** | **0.240** | **1.000** | **15 / 15** | 14 ms |
| grep (קו בסיס) | 0.227 | 0.967 | 15 / 15 | 0 ms |
שיעור פגיעה של 100% ב-top-5 בתקרה המתמטית של **P@5** עבור הקורפוס הזה (0.240, ראו scorecard). המצב ההיברידי שולף כל session זהב (gold); ל-grep חסר 1 מתוך 2 פריטי gold בשאילתה הטמפורלית המשתרעת על כמה sessions. השיפור הוא ב-**recall + טמפורליות**, לא בדיוק מצרפי. ה-benchmark הזה קטן ומעוט gold; 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 בלבד | 86.2% | 94.6% | 71.5% |
### חיסכון בטוקנים
| גישה | טוקנים/שנה | עלות/שנה |
|---|---|---|
| הדבקת הקשר מלא | 19.5M+ | בלתי אפשרי (חורג מהחלון) |
| סיכום על ידי LLM | ~650K | ~$500 |
| **agentmemory** | **~170K** | **~$10** |
| agentmemory + embeddings מקומיים | ~170K | **$0** |
> מודל embedding: `all-MiniLM-L6-v2` (מקומי, חינמי, בלי מפתח API). דוחות מלאים: [`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), harness עם adapters נתיקים עבור LongMemEval `_s` (500 שאלות ציבוריות) + `coding-agent-life-v1` (קורפוס פנימי של 15 sessions). מתאמי Grep / וקטור / agentmemory מקבלים ניקוד אחד לצד השני, פלט 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, pipelines לבנייה מרובת-סוכנים, וגרפי ידע רחבים יותר על פני docs / PDF / תמונות / וידאו. agentmemory זוכר את העבודה; שלושת הפרויקטים האלה מדליקים את שאר שכבת ההקשר. מתכונים + טבלת ניתוב שאלות: [`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
Built-in (CLAUDE.md)
סוג
מנוע זיכרון + שרת MCP
API של שכבת זיכרון
runtime מלא לסוכן
AI אישי
API זיכרון + אפליקציה
hub זיכרון לצוות (proxy ל-LLM)
זיכרון וקטורי (קוד פתוח)
מנוע זיכרון (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 hooks (ללא מאמץ ידני)
קריאות add() ידניות
עריכות עצמיות של הסוכן
ידני
חילוץ בצד ה-API
יירוט proxy (החלפת base-URL)
ידני
חילוץ API
ידני
עריכה ידנית
חיפוש
BM25 + וקטור + גרף (fusion מסוג RRF)
וקטור + גרף
וקטור (ארכיוני)
סמנטי
וקטור + RAG
4 סוגי נכסים (Chat / Skill / Wiki / CodeGraph)
וקטור בלבד
וקטור + סמנטי
משוקלל decay
טוען הכול להקשר
ריבוי-סוכנים
MCP + REST + leases + signals
API (בלי תיאום)
רק בתוך runtime של Letta
לא
לא
תפקידי צוות + נכסים משותפים
לא
מוגבל לתחום בלבד
משותף בין סוכנים מרובים
קבצים לפי סוכן
נעילה ל-framework
אין (כל לקוח MCP)
אין
גבוהה (חייבים להשתמש ב-Letta)
עצמאי (standalone)
אין
Proxy חוצץ בפני כל קריאת מודל
אין
Oracle Database
אין
פורמט לפי סוכן
תלויות חיצוניות
אין (SQLite + iii-engine)
Qdrant / pgvector
Postgres + מסד נתונים וקטורי
מרובות
cloud מנוהל
ערימת Docker (Core + Hub + Proxy)
מאגר וקטורי
Oracle AI Database
אין
אין
מחזור חיים של הזיכרון
קונסולידציה ב-4 שכבות + decay + שכחה אוטומטית
חילוץ פסיבי
מנוהל על ידי הסוכן
ידני
שכחה אוטומטית
בדיקה ידנית; ניתוב אוטומטי בפיתוח
אין
לא מצוין
decay + קונסולידציה
גיזום ידני
יעילות טוקנים
~1,900 טוקנים/session ($10/שנה)
משתנה לפי אינטגרציה
זיכרון core בתוך ההקשר
משתנה
תמחור cloud
לא מצוין
אין תקציב טוקנים
מגובה LLM (משתנה)
משתנה
22K+ טוקנים ב-240 תצפיות
מציג בזמן אמת
כן (פורט 3113)
dashboard ב-cloud
dashboard ב-cloud
UI מבוסס web
dashboard ב-cloud
UI web של ה-hub
לא
לא
לא
לא
אירוח עצמי
כן (ברירת מחדל)
אופציונלי
אופציונלי
כן
לא (cloud בלבד)
כן (Docker)
כן
כן (Oracle DB)
כן
כן
הערת benchmark: רק ה-R@5 של agentmemory הוא תוצאת מדידה שלנו (LongMemEval-S, ניתנת לשכפול מ-benchmark/COMPARISON.md). המספרים של mem0 ו-Letta הם המספרים המתפרסמים שלהם מ-LoCoMo (dataset שונה); המספרים של MemPalace, supermemory, TencentDB (PersonaMem), ו-oracleagentmemory הם טענות שדווחו על ידי היצרן ולא שכפלנו אותן באופן עצמאי (ההרצה של oracleagentmemory השתמשה ב-GPT-5.5 מול Oracle AI Database). מוצגים זה לצד זה להערכה כללית בלבד, לא כהשוואת ראש-בראש על אותם נתונים. ספירות הכוכבים הן משוערות ומשתנות עם הזמן.
**שחקנים חדשים יותר** שכדאי להכיר, מושווים בהרחבה ב-[`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
| מערכת | ⭐ | זווית |
|--------|---|-------|
| Zep / Graphiti | 30K | גרף ידע טמפורלי; תוצאות השאילתה הטמפורלית הפרסומיות החזקות ביותר (LongMemEval 63.8%), אבל הגרף נבנה באופן אסינכרוני כך שעובדות חדשות יכולות להתעכב |
| Cognee | 30K | בליעת מסמכים לגרף ידע (document-to-knowledge-graph), Python בלבד, נבנה לחילוץ ישויות מבני ולא ללכידת sessions |
אף אחד מהם לא לוכד אוטומטית מ-hooks של סוכן קוד, לא מגיע עם מציג local-first, ולא רץ במצב keyless — השילוב הזה הוא מה ש-agentmemory בנוי עליו.
---
תאימות: הגרסה הזו מיועדת ל-`iii-sdk` 0.22.1 ונעוצה לגרסה v0.22.1 של iii-engine.
### נסו את זה ב-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 sessions ריאליסטיים (JWT auth, תיקון שאילתת N+1, rate limiting) ומריץ עליהם חיפושים. התקנות keyless משביתות וקטורים, כך ששאילתות מילות המפתח של `mem::search` צריכות לפגוע ביעד באמצעות BM25 בעוד ש-`database performance optimization` יכולה להחזיר אפס. `smart-search` יכול גם להחזיר התאמות מבניות מהגרף כשנתוני גרף קיימים. כדי לגרום לשאילתה הסמנטית למצוא את תיקון ה-N+1 באמצעות וקטורים, יש להגדיר `EMBEDDING_PROVIDER=local`, להפעיל מחדש, ולאפשר להורדת המודל הראשונה להסתיים.
פתחו את `http://localhost:3113` כדי לראות את הזיכרון נבנה בזמן אמת.
### אימות התקנה חדשה והתמדה (persistence) אחרי הפעלה מחדש
כשהשרת רץ, יש לאמת את ה-REST, את ה-health, את המציג, ואת מצב ה-runtime המבוסס 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) שעולה בהפעלה מתייחס לכל ארבעת הפורטים: REST/MCP HTTP בפורט 3111, זרמי iii בפורט 3112, המציג בפורט 3113, וה-WebSocket של worker ה-iii בפורט 49134. `status` מאשר את ה-health של agentmemory ואת מצב הספק/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
```
### שידור חזרה (Replay) של session
כל session ש-agentmemory מקליט ניתן ל-replay. פתחו את המציג, בחרו בלשונית **Replay**, וגללו על פני ציר הזמן: prompts, קריאות tool, תוצאות tool, ותגובות מוצגים כאירועים נפרדים עם play/pause, שליטה במהירות (0.5x עד 4x), וקיצורי מקלדת (space להחלפה, חצים לדילוג שלב).
כדי להכניס תמלילי JSONL ישנים יותר של Claude Code:
```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
```
sessions מיובאים מופיעים בבורר ה-Replay לצד אלה המקוריים. מתחת למכסה המנוע, כל רשומה עוברת בפונקציות ה-iii `mem::replay::load`, `mem::replay::sessions`, ו-`mem::replay::import-jsonl`, בלי שרתי side-channel. כל תמליל מיובא מאונדקס לחיפוש, מתויג בערוץ מקור `import`, ונכרה לקבלת crystal של session ולקחים (lessons).
> **שימו לב אם אתם נשענים על `import-jsonl` כנתיב הלכידה העיקרי שלכם:** ה-`cleanupPeriodDays` של Claude Code (בקובץ `~/.claude/settings.json`, ברירת מחדל **30**) מוחק אוטומטית תמלילי JSONL ישנים מהחלון הזה מ-`~/.claude/projects/`. אם אתם מתקינים agentmemory בפעם הראשונה על היסטוריית Claude Code בת כמה חודשים, כל דבר שישן מ-30 יום כבר נעלם לפני היבוא הראשון. אפשר להריץ את `import-jsonl` ב-cron, להעלות את `cleanupPeriodDays` לערך גבוה יותר, או לחווט את ה-hooks של הלכידה האוטומטית (נתיב התקנת ה-plugin כברירת מחדל) כך שכל turn נוחת ב-agentmemory כל עוד ה-session חי והניקוי של JSONL מפסיק להיות רלוונטי.
### שדרוג / תחזוקה
השתמשו בפקודת התחזוקה כשאתם רוצים במכוון לעדכן את ה-runtime המקומי שלכם:
```bash
npx -y @agentmemory/agentmemory@latest upgrade
```
אזהרה: הפקודה הזו משנה את ה-workspace/runtime הנוכחי. היא יכולה לעדכן תלויות JavaScript ולמשוך את תמונת ה-Docker הנעוצה `iiidev/iii:0.22.1`. היא לעולם לא מתקינה iii engine לא-נעוץ או חדש יותר.
פרטי המימוש נמצאים בקובץ `src/cli.ts` (ראו `runUpgrade` באזור `src/cli.ts:544-595`).
### 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 בלבד)
אם אתם מחווטים את שרת ה-MCP של agentmemory ישירות דרך `~/.claude.json` במקום להשתמש ב-`/plugin install`, Claude Code לעולם לא פותר את `${CLAUDE_PLUGIN_ROOT}` ואתם חייבים להפנות את סקריפטי ה-hook ל-paths מוחלטים בתוך `~/.claude/settings.json`. ה-paths האלה בדרך כלל מטמיעים בתוכם את גרסת agentmemory (למשל `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), כך שהשדרוג הבא שובר בשקט כל hook.
פתרון עוקף:
```bash
agentmemory connect claude-code --with-hooks
```
זה ממזג את אותן פקודות hook לתוך `~/.claude/settings.json` עם paths מוחלטים שנפתרים לתיקיית `plugin/` המצורפת של חבילת `@agentmemory/agentmemory` המותקנת כעת. יש להריץ את הפקודה מחדש אחרי שדרוג agentmemory כדי לרפרש את ה-paths. רשומות משתמש בקובץ עצמו נשמרות; רק רשומות agentmemory קודמות מוחלפות. השימוש בנתיב `/plugin install` נשאר הגישה המומלצת.
ל-deployments מרוחקים או מוגנים, הפעילו את Claude Code עם `AGENTMEMORY_URL` ו-`AGENTMEMORY_SECRET` מוגדרים. ה-plugin מעביר את שני הערכים לשרת ה-MCP המצורף שלו; כש-`AGENTMEMORY_URL` ריק, ה-shim של MCP משתמש ב-`http://localhost:3111`.
### Codex CLI (פלטפורמת plugin של Codex)
```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
```
ה-plugin של Codex נשלח מתוך אותה תיקיית `plugin/` כמו ה-plugin של Claude Code. הוא רושם:
- גשר MCP מצורף מסוג stdio ל-daemon הרץ, בלי הורדת npm ובלי מאגר fallback. ראו את [מדריך ה-Codex המקומי](../docs/plugins/codex-local.md) כדי לבדוק build שלא פורסם.
- 6 hooks של מחזור חיים: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
- 9 skills שניתן להפעיל: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, בתוספת 8 skills של עיון (reference) שהסוכן טוען לפי הצורך (משמעת זיכרון, כלי MCP, REST API, תצורה, סוכנים, hooks, ארכיטקטורה, ומדריך כתיבת skills)
מנוע ה-hooks של Codex מזריק את `CLAUDE_PLUGIN_ROOT` לתוך תת-תהליכי ה-hook (לפי [`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 הם ייחודיים ל-Claude Code ולא רשומים עבור Codex.
#### אמון ב-hooks של Codex ותאימות
שילוח ה-hooks הנטיביים של ה-plugin מאומת עם Codex CLI 0.150.1. בטחו ב-hooks של ה-plugin לפני שאתם מצפים ללכידה. ההתנהגות ב-Desktop תלויה ב-runtime המצורף שלו; בדקו את `/hooks` ואשרו אירוע שנלכד לפני הפעלת פתרון עוקף.
אם ה-host שלכם דורש hooks גלובליים, שכפלו את הפקודות לתוך `~/.codex/hooks.json`. כש-MCP כבר מחווט, המתאם הנוכחי צריך `--force` כדי להגיע להתקנת ה-hooks:
```bash
agentmemory connect codex --with-hooks --force
```
זה ממזג hooks גלובליים וכותב מחדש את הרשומה של agentmemory MCP, בעוד שהרשומות הלא-קשורות נשמרות. בדקו הגדרות endpoint מותאמות אישית של agentmemory לפני השימוש ב-`--force`. הריצו מחדש אחרי שדרוג כדי לרפרש paths של סקריפטים. הפעילו או hooks נטיביים של ה-plugin או עותקים גלובליים כדי להימנע מלכידה כפולה.
### GitHub Copilot CLI
למצב ה-agent של VS Code, השתמשו ב-[מדריך Copilot MCP ולכידה אוטומטית](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). מתאם ה-CLI לא מגדיר את 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/mcp-config.json` כש-`COPILOT_HOME` מוגדר) ומשמר שרתים קיימים. ב-Windows מקורי זה המתאם ה-`connect` האוטומטי היחיד; יש להגדיר כל סוכן Windows מקורי אחר באופן ידני. `connect` תחת WSL נתמך רק כשהסוכן המיועד מותקן באותה סביבת WSL. Copilot קולט את שרת ה-MCP בהפעלה הבאה או אחרי `/mcp`. התקינו גם את ה-plugin כשאתם רוצים את חוויית ה-hook/skill המלאה.
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`
#### Skills מובנים דרך `npx skills add` (50+ סוכנים)
agentmemory שולח 17 skills בפורמט `/SKILL.md` בסטייל Claude Code: 9 skills של פעולה שניתן להפעיל (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) ו-8 skills של עיון שהסוכן טוען לפי הצורך (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). ה-skills של העיון נושאים טבלאות נתונים שנוצרות מהמקור, כך שהן לעולם לא נסחפות (drift). ה-CLI [`skills`](https://npmjs.com/package/skills) של vercel-labs מתקין אותם אוטומטית לתוך תיקיית ה-skills המובנית של הסוכן הקורא על פני 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 `:
- `agentmemory connect ` כותב את תצורת שרת ה-MCP כך שהכלים זמינים.
- `npx skills add rohitg00/agentmemory` מתקין את ה-skills כך שהסוכן יודע מתי לקרוא להם.
לכמה מהסוכנים שה-CLI של skills עדיין לא מכסה (Zed v1.3.x ומטה), שימו את 17 קבצי ה-SKILL.md בעצמכם תחת תיקיית ה-skills המובנית של הסוכן; אותו פורמט עובד בכל מקום.
#### בלוק MCP סטנדרטי
הרשומה של agentmemory היא **אותו בלוק שרת MCP** בכל host שמשתמש במבנה `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}"
}
}
```
**מזגו את הרשומה הזו לתוך האובייקט `mcpServers` הקיים** בקובץ התצורה של ה-host; אל תחליפו את הקובץ. אם לקובץ יש כבר שרתים אחרים, הוסיפו את `agentmemory` לידם כמפתח נוסף בתוך `mcpServers`. אם `mcpServers` חסר כליל, הדביקו את הבלוק בתוך `{ "mcpServers": { ... } }`. ה-placeholders מסוג `${VAR}` יורשים את `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` מה-shell בהפעלת שרת ה-MCP; משתנים לא מוגדרים מעבירים מחרוזות ריקות וה-shim חוזר ל-`http://localhost:3111`. רשומה אחת מחווטת מכסה גם deployments מקומיים וגם מרוחקים (k8s / מאחורי reverse-proxy).
| סוכן | קובץ תצורה | הערות |
|---|---|---|
| **Cursor (MCP בלבד)** | `~/.cursor/mcp.json` | מזגו לתוך `mcpServers`, או `agentmemory connect cursor`. deeplink בלחיצה אחת זמין גם באתר. |
| **Cursor (plugin מלא)** | `.cursor-plugin/` | רישום ב-Cursor Marketplace (ה-submission בבדיקה) או Cursor Settings → Plugins → local checkout. רושם 7 hooks של לכידה אוטומטית (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skills + שרת ה-MCP, כש-`AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` מנוהלים ב-dashboard של ה-plugin של Cursor. עובד ב-Cursor IDE וב-CLI `cursor-agent`; prompts של מצב print ב-CLI מתמלאים בדיעבד מתמליל ה-session בסוף ה-session. |
| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | מזגו לתוך `mcpServers`. הפעילו מחדש את Claude Desktop אחרי העריכה. |
| **Cline / Roo Code / Kilo Code** | הגדרות MCP של Cline (Settings UI → MCP Servers → Edit) | אותו בלוק `mcpServers`. |
| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` ממזג את רשומת ה-MCP; `--with-hooks` מוסיף שישה hooks מובנים של לכידה אוטומטית (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) עם matchers של tool באותיות קטנות של Devin. אמתו עם `devin mcp list` ו-`/hooks` בתוך devin. |
| **Devin CLI (plugin מלא)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` מתוך checkout רושם את כל 17 ה-skills כפקודות slash מסוג `/agentmemory:` בתוספת שרת ה-MCP. ה-hooks של plugin ב-Devin לא יכולים להפעיל `SessionStart`/`SessionEnd`, אז משלבים אותו עם `connect devin --with-hooks` ללכידה מלאה של session. |
| **Devin (cloud)** | Settings → Connections → MCP servers | הוסיפו MCP מותאם אישית (STDIO): command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` שמצביע על deployment של agentmemory נגיש ברשת בתוספת `AGENTMEMORY_SECRET` (sessions בענן לא יכולים להגיע ל-localhost — ראו [`deploy/`](../deploy/)). שמרו את ה-secret ב-Devin Secrets, ואז השתמשו ב-"Test listing tools" כדי לאמת ש-54 הכלים מופיעים. |
| **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 מלא)** | התקנת plugin של Copilot | `copilot plugin install rohitg00/agentmemory:plugin` עבור ה-plugin מתוך ה-subdir ב-GitHub. |
| **OpenClaw** | תצורת MCP של OpenClaw | אותו בלוק `mcpServers`. לעומק: `openclaw plugins install ./integrations/openclaw` תופס את slot הזיכרון של OpenClaw (עובר אוטומטית מ-`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 מלא)** | marketplace של plugin-ים ב-Codex | `codex plugin marketplace add rohitg00/agentmemory` ואז `codex plugin add agentmemory@agentmemory`. רושם MCP + 6 hooks של מחזור חיים + 17 skills. בטחו ב-hooks ואמתו לכידה ב-host שלכם; ראו [הגדרה ואימות של Codex](../docs/plugins/codex-local.md). |
| **OpenCode (MCP בלבד)** | `opencode.json` | מבנה שונה: מפתח `mcp` ב-top-level, command כמערך: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
| **OpenCode (plugin מלא)** | `plugin/opencode/` | 22 hooks של לכידה אוטומטית שמכסים מחזור חיים של session, הודעות, tools, שגיאות. ייחוס הפרויקט הוא per-session, כך שתהליך OpenCode אחד שמשתרע על כמה repositories מתעד כל session תחת הפרויקט שלו. שתי פקודות slash (`/recall`, `/remember`). העתיקו את `plugin/opencode/` ל-workspace של OpenCode שלכם והוסיפו את רשומת ה-plugin ל-`opencode.json`. ראו [`plugin/opencode/README.md`](../plugin/opencode/README.md) לטבלת ה-hooks המלאה + ניתוח הפערים. |
| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` מתקין את ה-extension המצורף לתוך תיקיית הגילוי האוטומטי של pi (recall בהתחלת הסוכן, capture בסיום הסוכן, כלי `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). `/reload` ב-pi רץ קולט את זה. [`integrations/pi`](../integrations/pi/) הוא גם חבילת pi (`pi install ./integrations/pi` מתוך checkout). |
| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` נותן את ספק הזיכרון בן 6 ה-hooks (prefetch, לכידת turn, סיום session, pre-compress, שיקוף MEMORY.md, בלוק system prompt). אמתו עם `hermes plugins doctor` ו-`hermes memory status`. ראו [`integrations/hermes`](../integrations/hermes/). |
| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` כותב את בלוק ה-`mcpServers` הסטנדרטי. ה-payload של ה-hook תואם-שדות ל-Claude Code, כך שסקריפטי ה-12 hooks הקיימים עובדים בלי שינוי; חווטו אותם דרך סקשן ה-`hooks` באותו `settings.json`. |
| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` מתקין MCP ו-hooks של לכידה בתיקיית ההתאמה האישית המשותפת. ראו [הגדרה ומגבלות של Antigravity](../docs/plugins/antigravity.md). |
| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` משתמש באותה תצורת MCP ו-hooks כמו גרסאות ה-IDE הנוכחיות. התקנות קיימות צריכות לרפרש עם `--force`; ראו את [הערות השדרוג](../docs/plugins/antigravity.md). |
| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` כותב את התצורה בשכבת המשתמש. override-ים בשכבת ה-workspace נכנסים ב-`.kiro/settings/mcp.json` לצד הקוד שלכם. |
| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` כותב את בלוק ה-`mcpServers` הסטנדרטי. Warp גם מגלה אוטומטית skills מ-`.claude/skills/`; כשה-plugin של Claude Code מותקן, 8 ה-skills של agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) מופיעים באופן מובנה בפלטת פקודות ה-slash של Warp. |
| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` כותב את בלוק ה-`mcpServers` הסטנדרטי. למשתמשי ה-extension של VS Code: הדביקו את אותו בלוק דרך Cline Settings → MCP Servers → Edit JSON. |
| **Continue.dev** | `~/.continue/config.yaml` (מועדף) או `config.json` (legacy) | `agentmemory connect continue` יוצר `config.yaml` מאפס כששניהם לא קיימים, או משנה `config.json` קיים. **אם יש לכם כבר `config.yaml`** המתאם מדפיס את הבלוק המדויק להדבקה תחת `mcpServers:`; הוא לא כותב מחדש בשקט את ה-yaml שלכם כי שמירה בטוחה על comments ועוגנים (anchors) מחייבת YAML parser שהחבילה לא מגיעה איתו. Continue משתמש בצורת מערך (לא object) עבור `mcpServers`. |
| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` כותב תחת `context_servers` (המפתח של Zed, לא `mcpServers`). שרתי MCP מרוחקים אפשר לחווט במקום זאת דרך `{"url": "..."}`. |
| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` כותב את בלוק ה-`mcpServers` הסטנדרטי. override-ים בתחום פרויקט נכנסים ב-`/.factory/mcp.json`. העבירו `--with-hooks` ללכידה אוטומטית מובנית. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` מוסיף שורת `@deepseek-ai/dsh-mcp-client` לשכבת ה-patch בשכבת ה-home שכל פרופיל Harness טוען; הכלים נרשמים כ-`mcp__agentmemory__*`. העבירו `--with-hooks` כדי לחווט גם לכידה אוטומטית: סקריפטי ה-hook המצורפים של Claude Code רצים דרך הגשר ה-first-party של Harness, `@deepseek-ai/dsh-hooks-claude-code` (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop), באמצעות manifest שנכתב ל-`$DSH_HOME/agentmemory.hooks.json`. ברירת המחדל היא `~/.dsh` כש-`DSH_HOME` לא מוגדר. |
| **Goose** | ממשק הגדרות MCP של Goose | אותו בלוק `mcpServers`; השתמשו ב-`goose configure` → Add Extension → MCP. עריכה ישירה של YAML ב-`~/.config/goose/config.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 וממזג. |
**לקוחות MCP ב-sandbox** (Flatpak / Snap / containers מגבילים) שלא יכולים להגיע ל-`localhost` של ה-host: הגדירו גם `"AGENTMEMORY_FORCE_PROXY": "1"` בבלוק ה-`env`, והפנו את `AGENTMEMORY_URL` למסלול שה-sandbox יכול בפועל להגיע אליו (למשל כתובת ה-LAN שלכם).
### גישה פרוגרמטית (Python / Rust / Node)
agentmemory רושם את הפעולות המרכזיות שלו כפונקציות 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). ה-REST בפורט `:3111` נשאר זמין ל-hosts בלי runtime של iii.
### מהמקור (From source)
```bash
git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start
```
זה מפעיל את agentmemory עם `iii-engine` מקומי אם הבינארי הנעוץ כבר מותקן, או משתמש ב-Docker Compose כשנבחר. REST, streams, והמציג נקשרים (bind) ל-`127.0.0.1` כברירת מחדל. הנתיב האוטומטי של הבינארי ב-macOS/Linux דורש `curl`, מעטפת `sh` תואמת POSIX, ו-`tar`.
התקינו את `iii-engine` ידנית. **agentmemory נעוץ כרגע ל-`iii-engine` בגרסה `v0.22.1`**, אותה גרסה כמו התלות ב-`iii-sdk`; ה-worker מדבר בפרוטוקול ה-wire של אותו מנוע, וגרסה 0.20.0 ארגנה מחדש את שטח ה-SDK, כך שהשניים זזים יחד בגרסאות agentmemory. override עם `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-x86_64-pc-windows-msvc.zip` מ-[iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) וחלצו את `iii.exe` ל-`%USERPROFILE%\.agentmemory\bin\iii.exe`
לכל archive יש קובץ `.sha256` תואם בעמוד ה-release; כשמחליפים פלטפורמה, משתמשים ב-hash של אותו קובץ בבדיקה שלמעלה (ב-Windows: `Get-FileHash`). המתקין האוטומטי ב-`npx @agentmemory/agentmemory` נעוץ ל-hashes האלה ומסרב ל-archive שלא תואם.
או השתמשו ב-Docker (ה-`docker-compose.yml` המצורף מוריד את `iiidev/iii:0.22.1`). תיעוד מלא: [iii.dev/docs](https://iii.dev/docs).
### Windows
agentmemory רץ על Windows 10/11, אבל חבילת ה-Node.js בלבד לא מספיקה; צריך גם את ה-runtime הנעוץ v0.22.1 של iii-engine כתהליך רץ ברקע. ה-CLI לא מחלץ אוטומטית את ה-ZIP של Windows, כך שמשתמשי Windows מקורי חייבים להתקין את `iii.exe` ידנית, להשתמש ב-WSL2, או לבחור ב-Docker Desktop.
חיווט MCP אוטומטי ב-Windows מקורי תומך רק ב-`agentmemory connect copilot-cli`. עבור Claude Code, Codex, Cursor, וכל סוכן Windows מקורי אחר, העתיקו את בלוק ה-MCP הידני מ[סוכנים אחרים](#other-agents) לתוך תצורת ה-Windows של אותו סוכן. הרצת `connect` ב-WSL מתאימה רק כשהסוכן המיועד מותקן גם הוא באותה סביבת WSL; הוא לא עורך את התצורה של סוכן שרץ על Windows host.
**אפשרות A: בינארי 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 standalone בלבד (בלי מנוע).** אם אתם צריכים רק את כלי ה-MCP לסוכן שלכם ולא צריכים את ה-REST API, המציג, או עבודות cron, דלגו על המנוע כליל:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
# or via the shim package:
npx -y @agentmemory/mcp
```
**דיאגנוסטיקה ל-Windows:** אם `npx -y @agentmemory/agentmemory@latest` נכשל, הריצו אותו מחדש עם `--verbose` כדי לראות את ה-stderr האמיתי של המנוע. תבניות כשל נפוצות:
| תסמין | תיקון |
|---|---|
| `The engine process started but the REST API never responded.` | אשרו שכל ארבעת הפורטים הנגזרים פנויים, אמתו שה-`iii.exe` הנעוץ נשאר חי, ואז הריצו מחדש עם `--verbose` ובדקו את ה-stderr שנלכד של המנוע |
| `Could not start iii-engine` | לא `iii.exe` ולא Docker מותקנים. ראו אפשרות A או B מעלה |
| קונפליקט פורטים | `netstat -ano \| findstr :3111` כדי לראות מה קשור (bound), ואז הרגו את התהליך או השתמשו ב-`--port ` |
| ה-fallback ל-Docker דולג למרות ש-Docker מותקן | הקפידו ש-Docker Desktop רץ בפועל (אייקון ב-system tray) |
> הערה: ה**מנוע** של iii הוא בינארי מוכן מראש, לא cargo crate, אז אל תנסו `cargo install` אותו. (ה**SDK-ים** של iii מתפרסמים ב-crates.io, npm, ו-PyPI, אבל agentmemory לא צריך אותם.) כל שיטות ההתקנה הנתמכות של המנוע נעוצות ל-v0.22.1: הבינארי המוכן מראש שלמעלה, נתיב ההתקנה האוטומטי של agentmemory ב-macOS/Linux (נדרשים `curl`, מעטפת `sh` תואמת POSIX, ו-`tar`), ותמונת ה-Docker `iiidev/iii:0.22.1`. `install.sh | sh` גולמי מה-upstream מתקין את המנוע העדכני ביותר, שב-agentmemory לא נתמך. השתמשו ב-`npx -y @agentmemory/agentmemory@latest`; ב-macOS/Linux הוא מביא את המנוע הנעוץ לתוך `~/.agentmemory/bin`.
---
פריסה
תבניות בלחיצה אחת ל-hosts מנוהלים. כל אחת שולחת Dockerfile עצמאי שמוריד את `@agentmemory/agentmemory` מ-npm ומעתיק את הבינארי של מנוע ה-iii מתוך תמונת ה-Docker Hub הרשמית `iiidev/iii`; לא נדרשת תמונת agentmemory בנויה מראש. אחסון מתמשך נקשר (mount) ב-`/data`; ה-entrypoint של האתחול הראשון מחליף את תצורת ה-iii המצורפת ב-npm (שנקשרת ל-`127.0.0.1`) בתצורה מותאמת-deploy שנקשרת ל-`0.0.0.0` ומשתמשת ב-paths מוחלטים של `/data`, מייצרת את ה-secret של HMAC, ואז מוריד הרשאות מ-`root` ל-`node` באמצעות `gosu` לפני הרצת (exec) ה-CLI של agentmemory.
כפתור הפריסה בלחיצה אחת של Render דורש `render.yaml` בשורש ה-repository, שאנחנו משאירים נקי בכוונה. השתמשו בזרימת ה-Render Blueprint המתועדת ב-[`deploy/render/`](.././deploy/render/README.md) כדי להפנות ל-blueprint שבתוך ה-repo באופן ידני.
פרטי הקמה מלאים (לכידת HMAC, SSH tunnel למציג, רוטציה, backup, רצפות עלות) נמצאים ב-[`deploy/`](.././deploy/README.md):
- [`deploy/fly`](.././deploy/fly/README.md): מכונה בודדת עם
`auto_stop_machines = "stop"`; הכי זול במנוחה (idle).
- [`deploy/railway`](.././deploy/railway/README.md): תשלום קבוע ב-Hobby plan,
volume ב-dashboard.
- [`deploy/render`](.././deploy/render/README.md): זרימת Blueprint,
snapshots אוטומטיים לדיסק בתוכניות בתשלום.
- [`deploy/coolify`](.././deploy/coolify/README.md): אירוח עצמי על ה-VPS
שלכם באמצעות [Coolify](https://coolify.io/self-hosted); אותה ערימת Docker
Compose, אתם הבעלים של ה-host ושל הנתונים.
רק פורט `3111` חשוף (published). המציג בפורט `3113` נשאר קשור
ל-loopback בתוך ה-container; ה-README של כל תבנית מתעד את תבנית
ה-SSH-tunnel להגיע אליו.
---
כל סוכן קוד שוכח הכול כש-session מסתיים, וכל session חדש מתחיל בכך שאתם מסבירים מחדש את ה-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. אלה עובדים כמו פתקיות דביקות. agentmemory הוא מסד הנתונים הניתן לחיפוש שמאחורי הפתקיות הדביקות.
| | מובנה (CLAUDE.md) | agentmemory |
|---|---|---|
| קנה מידה | מוגבל ל-200 שורות | בלתי מוגבל |
| חיפוש | טוען הכול להקשר | BM25 + וקטור + גרף (top-K בלבד) |
| עלות טוקנים | 22K+ ב-240 תצפיות | ~1,900 טוקנים (92% פחות) |
| בין-סוכנים | קבצים לפי סוכן | MCP + REST (כל סוכן) |
| תיאום | אין | leases, signals, actions, routines |
| Observability | קריאת קבצים ידנית | מציג בזמן אמת בפורט :3113 |
---
### צינור הזיכרון
```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 שכבות
מבוסס על האופן שבו מוח האדם מעבד זיכרון, כולל קונסולידציה בשינה.
| שכבה | מה | אנלוגיה |
|------|------|---------|
| **עבודה (Working)** | תצפיות גולמיות משימוש בכלים | זיכרון קצר-טווח |
| **אפיזודי (Episodic)** | סיכומי session דחוסים | "מה קרה" |
| **סמנטי (Semantic)** | עובדות ודפוסים שחולצו | "מה שאני יודע" |
| **פרוצדורלי (Procedural)** | workflows ודפוסי החלטה | "איך לעשות את זה" |
זיכרונות דועכים (decay) עם הזמן (עקומת Ebbinghaus). זיכרונות שנגישים אליהם לעיתים קרובות מתחזקים. זיכרונות שהתיישנו מתפנים (evict) אוטומטית. סתירות מתגלות ונפתרות.
### מה נלכד
| Hook | מה נלכד |
|------|----------|
| `SessionStart` | נתיב הפרויקט, מזהה ה-session |
| `UserPromptSubmit` | prompts של המשתמש (מסוננים לפרטיות) |
| `PreToolUse` | דפוסי גישה לקבצים + הקשר מועשר |
| `PostToolUse` | שם ה-tool, קלט, פלט |
| `PostToolUseFailure` | הקשר שגיאה |
| `PreCompact` | מזריק מחדש זיכרון לפני compaction |
| `SubagentStart/Stop` | מחזור חיים של תת-סוכן |
| `Stop` | סיכום סוף-session |
| `SessionEnd` | סימון השלמת session |
### יכולות מפתח
| יכולת | תיאור |
|---|---|
| **לכידה אוטומטית** | כל שימוש ב-tool נרשם דרך hooks, בלי מאמץ ידני |
| **חיפוש סמנטי** | BM25 + וקטור + גרף ידע עם fusion מסוג RRF |
| **אבולוציית זיכרון** | ניהול גרסאות, supersession, גרפי יחסים |
| **היגיינת שליפה (recall)** | גרסאות זיכרון שהוחלפו (superseded) עוזבות את אינדקסי החיפוש; שרשרת הגרסאות ב-KV שומרת היסטוריה מלאה |
| **אמצעי זהירות לכפילויות-כמעט** | שמירות מדווחות על התאמת `similarTo` מייעצת כשתוכן חדש מזכיר מאוד זיכרון קיים |
| **תחום לפי סוכן** | `agentId` עובר דרך שמירה ושליפה על פני REST, MCP, ואינדקס החיפוש, במצב shared או isolated |
| **מקור בזמן כתיבה (provenance)** | כל תצפית וזיכרון נושאים ערוץ מקור בלתי-ניתן-לשינוי (user, agent, tool, import, או shared) שמוחתם בזמן לכידה, שמירה, וייבוא |
| **שכחה אוטומטית** | תפוגת TTL, גילוי סתירות, פינוי לפי חשיבות |
| **פרטיות ראשית** | מפתחות API, secrets, תגי `` מוסרים לפני האחסון |
| **החלמה עצמית (self-healing)** | circuit breaker, שרשרת fallback לספקים, מעקב health |
| **גשר Claude** | sync דו-כיווני עם MEMORY.md |
| **גרף ידע** | חילוץ ישויות + מעבר (traversal) מסוג BFS |
| **זיכרון צוותי** | שיתוף + פרטיות עם namespace בין חברי הצוות |
| **מקור ציטוט** | עקבו אחורה מכל זיכרון לתצפיות המקור |
| **snapshots של Git** | גרסה, rollback, ו-diff על מצב הזיכרון |
---
שליפה בשלושה זרמים שמשלבת שלושה סיגנלים:
| זרם | מה הוא עושה | מתי |
|---|---|---|
| **BM25** | התאמת מילות מפתח עם stemming והרחבת מילים נרדפות | פעיל תמיד |
| **וקטור** | דמיון קוסינוס מעל embeddings צפופים | כשספק embedding מוגדר |
| **גרף** | מעבר בגרף ידע באמצעות התאמת ישויות | כשישויות מתגלות בשאילתה |
ממוזגים (fused) עם Reciprocal Rank Fusion (RRF, k=60) ומגוונים לפי session (עד 3 תוצאות ל-session).
כשאינדקס וקטורי מאוכלס, `mem::search` (מאחורי `memory_recall`) משתמש ב-ranker ההיברידי של BM25 + וקטור. בלי embeddings הוא משתמש ב-BM25. `smart-search` יכול גם למזג התאמות מבניות מהגרף כשנתוני גרף קיימים, גם במצב keyless. שליפת lessons רצה על אינדקס BM25 ייעודי בזיכרון במקום לסקור את כל הקורפוס בכל שאילתה. גרסאות זיכרון שהוחלפו (superseded) מוחרגות מכל נתיב שליפה; שרשרת הגרסאות שומרת את ההיסטוריה שלהן.
וקטורים שורדים קריסה או force-kill. אינדקס הווקטורים נשמר ב-buckets לכל היותר כל `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 דקות). כל וקטור שנוסף או הוסר בינתיים גם נכתב מיידית ל-log קטן של pending ב-state store, וההפעלה הבאה משדרת אותו (replay) מחדש בלי לקרוא לספק ה-embedding. כל שמירה מוצלחת מרוקנת את ה-log. מסמכים שעדיין אין להם וקטור אחרי ה-replay מוטבעים (re-embedded) מחדש ברקע ב-batches של `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) עד שלא נשאר אף אחד, ו-backfill שנעצר ממשיך בהפעלה הבאה. `/agentmemory/status` והמציג מציגים את גודל ה-log הממתין ואת מצב ה-backfill. התקנות keyless לא כותבות שום דבר.
BM25 מבצע tokenization ליוונית, קירילית, עברית, ערבית, ולטינית עם סימני הטעמה ישר מהקופסה. לזיכרונות בסינית / יפנית / קוריאנית, התקינו את ה-segmenters האופציונליים (`npm install @node-rs/jieba tiny-segmenter`) כדי לפצל רצפי CJK ל-tokens בגובה-מילה; בלעדיהם, agentmemory נופל בעדינות ל-tokenization של הרצף השלם ומדפיס רמז חד-פעמי ל-stderr.
### ספקי Embedding
התקנות keyless משביתות embeddings וקטוריים: `mem::search` משתמש ב-BM25, בעוד ש-`smart-search` יכול גם להשתמש בנתוני גרף מבניים קיימים. כדי להפעיל embeddings סמנטיים חינמיים במכשיר עצמו, הוסיפו את זה ל-`~/.agentmemory/.env` והפעילו מחדש את agentmemory:
```env
EMBEDDING_PROVIDER=local
```
ה-npm install הרגיל כולל את ה-runtime האופציונלי `@huggingface/transformers`. בקשת ה-embedding הראשונה מורידה את `Xenova/all-MiniLM-L6-v2`, כך שהיא צריכה גישת רשת ויכולה לקחת יותר זמן; ההסקה הבאה רצה במכשיר עצמו. ספקים מרוחקים מתגלים אוטומטית מהמפתחות שלהם אלא אם `EMBEDDING_PROVIDER` גובר עליהם.
| ספק | מודל | עלות | הערות |
|---|---|---|---|
| **מקומי (opt-in מומלץ)** | `all-MiniLM-L6-v2` | חינמי | במכשיר עצמו אחרי הורדת המודל הראשונה, +8pp ל-recall לעומת BM25 בלבד |
| Gemini | `gemini-embedding-001` | שכבה חינמית | 100+ שפות, 768/1536/3072 מימדים (MRL), קלט של 2048 טוקנים. מחליף את `text-embedding-004` ([הוצא משימוש, כיבוי ב-14 בינואר 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
| OpenAI | `text-embedding-3-small` | $0.02/1M | האיכות הגבוהה ביותר |
| Voyage AI | `voyage-code-3` | בתשלום | מותאם לקוד |
| Cohere | `embed-english-v3.0` | ניסיון חינמי | כללי |
| OpenRouter | כל מודל | משתנה | proxy מרובה-מודלים |
---
54 כלים, 6 משאבים, 3 פרומפטים, ו-17 skills.
> **shim MCP לעומת שרת מלא:** חבילת `@agentmemory/mcp` המתפרסמת היא shim דק. היא חושפת את שטח ה-54-הכלים המלא **רק כשהיא מצליחה להגיע לשרת agentmemory רץ** דרך `AGENTMEMORY_URL` (מצב proxy). בלי שרת נגיש, ה-shim חוזר לסט מקומי של 7 כלים (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). משתנה הסביבה `AGENTMEMORY_TOOLS=core|all` הוא דגל *בצד השרת*; הגדרתו בבלוק ה-`env` של ה-shim אין לה שום אפקט. אם אתם רואים רק 7 כלים ב-Cursor / OpenCode / Gemini CLI, הפעילו את `npx -y @agentmemory/agentmemory@latest` (או את ערימת ה-Docker) והגדירו `AGENTMEMORY_URL=http://localhost:3111`.
### 54 כלים
שלושה שטחי כלים, מהקטן לגדול: `AGENTMEMORY_TOOLS=core` מגביל את הנראות ל-8 כלים חיוניים (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); הסט הבסיסי שלהלן הוא 14 הכלים הבסיסיים של הרשימה (registry); ברירת המחדל (`AGENTMEMORY_TOOLS=all`) חושפת את כל 54.
כלי בסיס (14)
| כלי | תיאור |
|------|-------------|
| `memory_recall` | חיפוש תצפיות עבר |
| `memory_compress_file` | דחיסת קבצי markdown בשמירה על המבנה |
| `memory_save` | שמירת תובנה, החלטה, או דפוס |
| `memory_file_history` | תצפיות עבר על קבצים ספציפיים |
| `memory_patterns` | גילוי דפוסים חזרתיים |
| `memory_sessions` | רשימת sessions אחרונים |
| `memory_smart_search` | חיפוש היברידי סמנטי + מילות מפתח |
| `memory_vision_search` | חיפוש תצפיות תמונה |
| `memory_timeline` | תצפיות כרונולוגיות |
| `memory_profile` | פרופיל פרויקט (קונספטים, קבצים, דפוסים) |
| `memory_export` | ייצוא כל נתוני הזיכרון |
| `memory_relations` | שאילתה על גרף היחסים |
| `memory_commit_lookup` | sessions שמאחורי git commit |
| `memory_commits` | commits שנרשמו ל-session |
כלים מורחבים (54 בסך הכול, שטח ברירת המחדל)
| כלי | תיאור |
|------|-------------|
| `memory_patterns` | גילוי דפוסים חזרתיים |
| `memory_timeline` | תצפיות כרונולוגיות |
| `memory_relations` | שאילתה על גרף היחסים |
| `memory_graph_query` | מעבר בגרף ידע |
| `memory_consolidate` | הרצת קונסולידציה ב-4 שכבות |
| `memory_claude_bridge_sync` | sync עם MEMORY.md |
| `memory_team_share` | שיתוף עם חברי הצוות |
| `memory_team_feed` | פריטים משותפים אחרונים |
| `memory_audit` | audit trail של פעולות |
| `memory_governance_delete` | מחיקה עם audit trail |
| `memory_snapshot_create` | snapshot עם ניהול גרסאות ב-Git |
| `memory_action_create` | יצירת פריטי עבודה עם תלויות |
| `memory_action_update` | עדכון סטטוס action |
| `memory_frontier` | actions לא חסומים ממוינים לפי עדיפות |
| `memory_next` | ה-action הבא החשוב ביותר |
| `memory_lease` | leases בלעדיים ל-action (ריבוי-סוכנים) |
| `memory_routine_run` | הפעלת routines של workflow |
| `memory_signal_send` | הודעות בין-סוכנים |
| `memory_signal_read` | קריאת הודעות עם אישורי קבלה |
| `memory_checkpoint` | שערי תנאי חיצוניים |
| `memory_mesh_sync` | sync מסוג P2P בין instances |
| `memory_sentinel_create` | watchers מבוססי-אירועים |
| `memory_sentinel_trigger` | הפעלת sentinels מבחוץ |
| `memory_sketch_create` | גרפי action זמניים |
| `memory_sketch_promote` | קידום לקבוע |
| `memory_crystallize` | דחיסת שרשראות action |
| `memory_diagnose` | בדיקות health |
| `memory_heal` | תיקון אוטומטי של מצב תקוע |
| `memory_facet_tag` | תגים מסוג dimension:value |
| `memory_facet_query` | שאילתה לפי תגי facet |
| `memory_verify` | עקיבה אחר מקור (provenance) |
### 6 משאבים · 3 פרומפטים · 17 Skills
| סוג | שם | תיאור |
|------|------|-------------|
| משאב | `agentmemory://status` | Health, ספירת sessions, ספירת זיכרונות |
| משאב | `agentmemory://project/{name}/profile` | אינטליגנציה לפי פרויקט |
| משאב | `agentmemory://project/{name}/recent` | תצפיות אחרונות לפרויקט |
| משאב | `agentmemory://memories/latest` | 10 הזיכרונות הפעילים האחרונים |
| משאב | `agentmemory://graph/stats` | סטטיסטיקות גרף ידע |
| משאב | `agentmemory://team/{id}/profile` | פרופיל צוות משותף |
| פרומפט | `recall_context` | חיפוש + החזרת הודעות הקשר |
| פרומפט | `session_handoff` | נתוני handoff בין סוכנים |
| פרומפט | `detect_patterns` | ניתוח דפוסים חזרתיים |
| Skill | `/recall` | חיפוש בזיכרון |
| Skill | `/remember` | שמירה לזיכרון ארוך-טווח |
| Skill | `/session-history` | סיכומי sessions אחרונים |
| Skill | `/forget` | מחיקת תצפיות/sessions |
הטבלה מציגה את ארבעת ה-skills הבסיסיים. הסט המלא הוא 9 skills שניתן להפעיל בתוספת 8 skills של עיון; ראו את סקשן ה-skills המובנים מעלה.
### MCP עצמאי (Standalone)
הריצו בלי השרת המלא, לכל לקוח 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` לתוך האובייקט `mcpServers` הקיים של ה-host שלכם במקום להחליף את הקובץ. ללקוחות ב-sandbox שלא יכולים להגיע ל-`localhost` של ה-host, הוסיפו `"AGENTMEMORY_FORCE_PROXY": "1"` לבלוק ה-env והגדירו את `AGENTMEMORY_URL` למסלול שה-sandbox יכול להגיע אליו.
OpenCode (`opencode.json`):
```json
{
"mcp": {
"agentmemory": {
"type": "local",
"command": ["npx", "-y", "@agentmemory/mcp"],
"enabled": true
}
},
"plugin": ["./plugins/agentmemory-capture.ts"]
}
```
העתיקו את קובץ ה-plugin מה-repo:
```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`) ואז מחיל אירועי stream חיים: זיכרונות חדשים, lessons, תצפיות, רשומות audit, שינויי גרף ועדכוני health מופיעים בלי polling או רילוד של הדף. הבקשות האחרות היחידות הן הפעולות שאתם מקליקים, עמודי "טען עוד" וחיפושים. כשה-stream נופל, המציג מציג כמה זמן המספרים שלו ישנים, מתחבר מחדש עם backoff ומסתנכרן מחדש מ-snapshot אחד.
- **12 לשוניות בארבע קבוצות** עם ספירות חיות, deep links (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), קיצורי מקלדת, ותפריט מובייל.
- **זיכרונות:** חיפוש בצד השרת, filters לפי פרויקט, סוכן וסוג, פאנל פרטים עם שרשרת הגרסאות ו-word diff, קישורי provenance, כפתורי copy למזהה, לקריאת ה-MCP ולפקודת curl, עריכה (גרסה חדשה), forget עם אישור, forget בכמות (bulk) וייצוא JSON.
- **Sessions:** ציר זמן תצפיות inline עם קלט ופלט tool קריאים, filters ו-paging, והזיכרונות וה-lessons שכל session הפיק.
- **גרף:** חיפוש, פרטי node עם יחסים ומקורות, legend שלא מתבסס על צבע בלבד, ובקרות zoom.
- **Health:** הגרסה החיה של `GET /agentmemory/status`. לכל בעיה מגיע התיקון שלה, בתוספת ה-state backend, מצב שמירת האינדקס, התקדמות הדחיסה (compaction) של provenance בגרף, ומסביר קונסולידציה עם הסֲפים האמיתיים.
- עמודי **Audit, Activity, Profile, Replay, Lessons, Actions ו-Crystals**, כל אחד עם מצב ריק שאומר מה הסקשן הזה, למה הוא ריק, ואיזו פקודה מאכלסת אותו, ותיאור tooltip של `?` בכל מונח ומספר.
```bash
open http://localhost:3113
```
שרת המציג נקשר (bind) ל-`127.0.0.1` כברירת מחדל ומצרף את ה-secret של השרת כשהוא מעביר בקשות ל-REST API, כך שהוא לא דורש הגדרה. ה-endpoint `/agentmemory/viewer` המוגש דרך REST עוקב אחרי כללי bearer-token הרגילים ומפנה דפדפנים בלי token לפורט המציג. כותרות CSP משתמשות ב-nonce של script לכל תגובה ומשביתות attributes של handler inline (`script-src-attr 'none'`).
---
המציג בפורט `:3113` מציג מה הסוכן שלכם **זכר**. [קונסולת iii](https://iii.dev/docs/console) מציגה מה הסוכן שלכם **עשה**: כל פעולת זיכרון כ-trace של OpenTelemetry, כל רשומת KV ניתנת לעריכה, כל פונקציה ניתנת להפעלה, כל stream ניתן להאזנה (tap). שני חלונות על אותו זיכרון: אחד בצורת מוצר, אחד בצורת מנוע.
צפו ב-`memory_smart_search` מופעל וראו את סריקת ה-BM25 → חיפוש ה-embedding → fusion של RRF → reranker כ-waterfall. ערכו טיימר קונסולידציה תקוע ב-KV browser. בצעו replay ל-hook `PostToolUse` עם payload משופר. הצמידו (pin) את ה-stream של ה-WebSocket וצפו בתצפיות נוחתות בשידור חי.
agentmemory מקבל את זה בחינם כי כל קריאת פונקציה וכל trigger עוברים דרך iii; שום דבר מותאם אישית, שום דבר להתקין לו instrumentation.
עמוד ה-Workers: כל worker מחובר, כולל agentmemory עצמו, עם PID, ספירת פונקציות, runtime, ו-last-seen.
**מותקן כבר.** הקונסולה נשלחת עם מנוע ה-`iii` הנעוץ (0.22+); אין צורך להתקין שום דבר בנפרד. ההפעלה הראשונה מורידה את הבינארי של הקונסולה לצד המנוע.
**הפעלה לצד agentmemory:**
```bash
agentmemory console
```
זה מריץ את `iii console` של המנוע הנעוץ מול הפורטים ש-agentmemory פתר (REST, streams, bridge) ומגיש אותה פורט אחד מעל המציג, `http://localhost:3114` כברירת מחדל. `--console-port N` בוחר פורט אחר; `--port` ו-`--instance` בוחרים את instance ה-agentmemory באותו אופן שהם עושים ל-`stop`; כל דגל אחר מועבר הלאה, למשל `--enable-flow` לעמוד גרף הארכיטקטורה הניסיוני.
אותו דבר ביד, שימושי כש-`agentmemory` לא נמצא ב-PATH:
```bash
~/.agentmemory/bin/iii console --port 3114 \
--engine-port 3111 \
--ws-port 3112 \
--bridge-port 49134
```
**מה אפשר לעשות מהקונסולה:**
| עמוד | לשם מה להשתמש בו |
|------|-----------|
| **Workers** | לראות כל worker מחובר ואת המטריקות החיות שלו, כולל ה-worker של agentmemory עצמו. |
| **Functions** | להפעיל כל פונקציה של agentmemory ישירות עם payload של JSON; שימושי לבדיקת `memory.recall`, `memory.consolidate`, `graph.query` בלי לחווט לקוח. |
| **Triggers** | לבצע replay ל-triggers מסוג HTTP, cron, event, ו-state: להפעיל את ה-cron של הקונסולידציה ידנית, לנסות שוב route של HTTP, לפלוט שינוי state. |
| **States** | KV browser עם CRUD מלא על sessions, memory slots, טיימרי מחזור חיים, ואינדקס ה-embeddings; עריכת ערכים במקום. |
| **Streams** | מוניטור WebSocket חי לכתיבות זיכרון, אירועי hook, ועדכוני תצפית כשהם זורמים דרך streams של iii. |
| **Queues** | נושאי queue מתמשכים + ניהול dead-letter. replay או drop לעבודות embedding / דחיסה שנכשלו. |
| **Traces** | תצוגות waterfall / flame / פירוק-לפי-שירות של OpenTelemetry. סננו לפי `trace_id` כדי לראות בדיוק אילו functions, קריאות DB, ובקשות embedding יצר `memory.search` בודד. |
| **Logs** | logs מבניים של OTEL מסוננים ומקושרים (correlated) למזהי trace/span. |
| **Config** | תצורת runtime: לראות בדיוק עם אילו workers, ספקים, ופורטים המנוע שלכם רץ. |
| **Flow** | (אופציונלי, `--enable-flow`) גרף ארכיטקטורה אינטראקטיבי של כל worker, trigger, ו-stream. |
Traces: waterfall / flame / פירוק-שירות לכל פעולת זיכרון.
**Traces כבר פעילים:**
`iii-config.yaml` נשלח עם ה-worker `iii-observability` מופעל (`exporter: memory`, `sampling_ratio: 0.1`, metrics + logs). אין צורך בתצורה נוספת; ברגע ש-agentmemory מתחיל, כל פעולת זיכרון פולטת log מבני שהקונסולה יכולה לקרוא, ואחת מכל עשר מהן (`sampling_ratio: 0.1`) פולטת גם span של trace.
אם אתם רוצים לייצא ל-Jaeger/Honeycomb/Grafana Tempo במקום, שנו את `exporter: memory` ל-`exporter: otlp` והגדירו את ה-endpoint של ה-collector לפי תיעוד ה-observability של iii.
> **שימו לב:** אין auth מאולץ על הקונסולה עצמה; השאירו אותה קשורה ל-`127.0.0.1` (ברירת המחדל) ואל תחשפו אותה לעולם באופן ציבורי.
---
agentmemory הוא **כבר instance רץ של [iii](https://iii.dev)**. שלושה primitives (worker, function, trigger) מרכיבים את ה-runtime; מצב KV, streams, ו-OTEL traces מגיעים מ-workers בשם iii-state, iii-stream, ו-iii-observability שמגיעים עם iii. לא התקנתם Postgres, Redis, Express, pm2, או Prometheus, כי iii מחליף אותם.
זה אומר שפקודה אחת נוספת מרחיבה את agentmemory עם יכולת חדשה שלמה.
### הרחבת agentmemory עם עוד workers
ה-builtins ש-agentmemory צריך נמצאים כבר ב-`iii-config.yaml` ועולים (boot) איתו: `iii-state` (KV), `iii-queue` (retries מתמשכים למנויי האירועים), `iii-pubsub`, `iii-cron`, `iii-stream`, ו-`iii-observability` (OTEL traces, metrics ו-logs על כל פונקציה). כל דבר אחר מ-[רשימת ה-workers של iii](https://workers.iii.dev) מתחבר לאותו מנוע: העתיקו את `iii-config.yaml` ל-`~/.agentmemory/iii-config.yaml` (ה-CLI מעדיף את הקובץ הזה על פני המצורף ועדיין מרנדר אליו ports ו-paths של נתונים), הוסיפו את הרשומה, התקינו את ה-runtime של ה-worker פעם אחת עם `~/.agentmemory/bin/iii update 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) | מתאם state מבוסס-SQL כשאתם גדלים מעבר לברירות המחדל של KV בזיכרון |
| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | קוד שיצא מ-`memory_recall` רץ בתוך VM חד-שימושי, לא ב-shell שלכם |
| [`mcp`](https://workers.iii.dev/workers/mcp) | הקימו שרתי MCP נוספים לצד זה של agentmemory, שתפו את אותו מנוע |
במנוע 0.22.x השאירו את השמות עם ה-prefix `iii-` עבור ה-builtins שלמעלה; הרשומות בלי prefix `http`, `state`, `queue`, `pubsub` ו-`cron` הן ה-workers העצמאיים מהרשימה (registry) ש-agentmemory עובר אליהם עם מעבר הגרסה ל-0.23.
רשימה (registry) מלאה: [workers.iii.dev](https://workers.iii.dev). כל worker שם מורכב (composes) דרך אותם primitives ש-agentmemory משתמש בהם, וה-agentmemory שכבר יש לכם הוא אחד מהם.
### תצורת מנוע וכתובת bind
`agentmemory start` קורא את תצורת המנוע מהקובץ הראשון שקיים: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` בתיקייה הנוכחית, `~/.agentmemory/iii-config.yaml`, ואז `iii-config.yaml` המצורף. בכל הפעלה הוא מרנדר את הקובץ הזה (paths של נתונים, ports, state backend) לתוך `~/.agentmemory/data/iii-config.runtime.yaml` ומפעיל את המנוע עם העותק המרונדר, אז יש לערוך את קובץ המקור, לא את המרונדר. ערכי `host:` של קובץ המקור נשמרים כמו שהם נכתבו.
ה-`iii-config.yaml` המצורף נקשר ל-`127.0.0.1` בכוונה, וברירת המחדל הזו חלה גם בתוך container. CLI שמופעל בתוך container מקשיב ל-loopback של ה-container, כך שה-ports המפורסמים לא מגיעים לשום מקום. כדי להגיש CLI בתוך container דרך ports מפורסמים, הגדירו את `AGENTMEMORY_III_CONFIG` לתצורה שנקשרת ל-`0.0.0.0`. ה-`iii-config.docker.yaml` הארוז הוא אחת כזו: היא קושרת את `iii-http`, `iii-stream` ואת port המנוע ל-`0.0.0.0` ושומרת את ה-state תחת `/data`, אז יש לקשר volume לכתיבה שם. השאירו את `AGENTMEMORY_SECRET` מוגדר, ופרסמו רק את ה-ports שאתם צריכים, על `127.0.0.1` או מאחורי proxy שאתם סומכים עליו.
ה-`docker-compose.yml` של ה-repo הזה לא עובר דרך חיפוש התצורה של ה-CLI: הוא מקשר את `iii-config.docker.yaml` ב-`/app/config.yaml`, וה-container `iii-engine` מתחיל עם `--config /app/config.yaml`. [תבניות הפריסה](../deploy/) בלחיצה אחת כותבות תצורת `0.0.0.0` משלהן ב-entrypoints שלהן.
### Storage backend: file (ברירת מחדל) לעומת redis
`iii-state` ו-`iii-stream` כברירת מחדל משתמשים במאגר KV מבוסס-קבצים המצורף של iii-engine: קובץ JSON אחד לכל scope, מוחזק בזיכרון של תהליך המנוע ונכתב מחדש לדיסק בטיימר. זו ברירת המחדל הנכונה להתקנה מקומית למשתמש בודד; daemon משותף עם כמה כותבים (writers) מקבילים מקבל במקום זאת כתיבות אמיתיות per-key מ-Redis, במחיר של round trip רשת בכל פעולה (כל קריאת `state::*` עדיין מסתדרת (serializes) על חיבור Redis אחד, אז זה מחליף את ה-lock של מאגר הקבצים ב-socket, לא בפרלליות).
הגדירו `AGENTMEMORY_STATE_BACKEND=redis` (בתוספת `AGENTMEMORY_REDIS_URL`) כדי להחליף את שני ה-workers למתאם ה-`redis` המובנה של iii-engine, שמאחסן כל מפתח כשדה hash של Redis (`HSET`) במקום לכתוב מחדש scope שלם בכל כתיבה:
```env
# ~/.agentmemory/.env
AGENTMEMORY_STATE_BACKEND=redis
AGENTMEMORY_REDIS_URL=redis://localhost:6379
```
`AGENTMEMORY_STATE_BACKEND` כברירת מחדל הוא `file`; השארתו לא מוגדרת משאירה את ההתנהגות הנוכחית ללא שינוי, וערך לא מוכר (כל דבר חוץ מ-`file` או `redis`) הוא שגיאת startup ולא fallback שקט. `/agentmemory/status` ועמוד ה-Health של המציג (שורת State store) מדווחים איזה backend פעיל ואם הוא עונה, לעולם לא את ה-URL.
**`redis://` רגיל בלבד.** המנוע הנעוץ (0.22.1) בונה את לקוח ה-Redis שלו בלי תמיכת TLS, כך ש-URL מסוג `rediss://` (רוב שירותי ה-Redis המנוהלים, כמו Upstash, Redis Cloud, ו-ElastiCache עם הצפנה in-transit, שברירת המחדל שלהם היא TLS-only) נכשל להתחבר. החיבור לא מוצפן, כך שהסיסמה של Redis וכל זיכרון שמאוחסן עוברים ב-wire בטקסט גלוי: הפנו ל-Redis מקומי או כזה ברשת פרטית שאתם סומכים עליה. לכל Redis אחר, הריצו tunnel מוצפן (stunnel, SSH, או VPN) על ה-host של agentmemory, כך שה-hop של `redis://` הרגיל נשאר על ה-host הזה והחיבור upstream של ה-tunnel מוצפן ומאומת. אם סיסמת Redis מכילה גרש בודד, בצעו לה percent-encode (`%27`); המנוע מרחיב את ה-URL לתוך תצורת ה-YAML שלו לפני ה-parsing.
**שרת Redis אחד לכל `--instance`.** ה-prefixes של מפתחות Redis של המנוע (`state:`, `stream::`) קבועים, כך ששני instances של agentmemory (`--instance 1`, `--instance 2`, ...) שמצביעים על אותו database כותבים זה על גבי הנתונים של זה. אינדקס database נפרד (`redis://localhost:6379/1`) מפריד בין הנתונים המאוחסנים, אבל המנוע מעביר אירועי מציג חיים מעל ערוץ pub/sub אחד של Redis (`stream::events`), ו-pub/sub של Redis מתעלם מאינדקס ה-database, כך שהמציג של כל instance עדיין יראה את האירועים החיים של האחר. תנו לכל instance שרת Redis משלו (או port) כשאתם מריצים יותר מאחד.
**מה נשאר אותו דבר, ומה שונה.** כל יכולת של agentmemory עובדת על Redis: sessions, תצפיות, זיכרונות (remember, supersede, evolve, forget), חיפוש ו-buckets של האינדקס, lessons, הגרף, audit log וה-scopes החודשיים שלו, ייצוא וייבוא, מחיקות governance, סטטוס קונסולידציה, ה-snapshot של המציג וה-stream החי שלו, ומוניטור ה-health. המנוע מאחסן כל scope כ-hash אחד של Redis (`HSET`/`HGET`/`HGETALL`) ומפעיל את אותם state triggers כמו מאגר הקבצים. שלושה הבדלי מנוע מטופלים בתוך agentmemory:
- Redis מחזיר את הרשומות של scope בלי סדר קבוע. agentmemory ממיין אותן מהישן ביותר ראשון (לפי זמן היצירה שבתוך מזהה הרשומה, ואז ה-timestamp שלה) כך ש-lists, paging, ו-chunks של ייצוא חוזרים באותו סדר כמו במאגר הקבצים.
- המנוע מחיל עדכונים חלקיים על Redis בסקריפט Lua שמהפך מערכים ריקים לאובייקטים ריקים. agentmemory מחיל את העדכונים האלה בעצמו (read, change, write תחת lock per-key) על Redis, כך ששדות כמו `tags: []` נשארים מערכים.
- בדיקת ה-audit log הישנה (legacy) קוראת את ה-scope הישן מ-Redis במקום לחפש את הקובץ של מאגר הקבצים על הדיסק.
הבדל אחד דורש מכם פעולה: **אחרי ש-Redis מופעל מחדש, המנוע מפסיק להעביר אירועים חיים** למציג עד ש-agentmemory מופעל מחדש. הנתונים עדיין נשמרים ונקראים כרגיל. מוניטור ה-health שולח אירוע בדיקה דרך Redis כל 30 שניות; כשהוא לא חוזר, `/agentmemory/status` ועמוד ה-Health של המציג מציגים "Live updates are not reaching the viewer" עם התיקון: הפעילו מחדש את agentmemory. אם Redis למטה, דוח הסטטוס מציג "The state store is not answering" ואיך לבדוק את זה (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). רישום (listing) של scope גדול מאוד קורא את כל ה-hash ב-`HGETALL` אחד, אותו עלות כמו מאגר הקבצים שמחזיק אותו בזיכרון.
**הגדרות Redis מומלצות.** מדיניות ה-snapshot של ברירת המחדל `save 3600 1 300 100 60 10000` יכולה להפסיד דקות של כתיבות בקריסה, גרוע יותר מחלון ה-flush של 5 שניות של מאגר הקבצים. הגדירו `appendonly yes` לכל דבר שיהיה לכם חשוב לא להפסיד. הגדירו `maxmemory-policy noeviction`; `allkeys-lru` או דומה מפילים זיכרונות בשקט כש-Redis מגיע למגבלת הזיכרון שלו.
הפעלה native (לא-Docker), וכל [תבנית פריסה](../deploy/) בלחיצה אחת (הן כותבות מחדש את `iii-config.yaml` המצורף ומתחילות native), קוראות את `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` ומרנדרות אותן לתוך ה-`iii-config` שמופעל. ה-URL עצמו לעולם לא נכתב לקובץ המרונדר הזה, רק reference מסוג `${AGENTMEMORY_REDIS_URL}` שתהליך המנוע מרחיב מהסביבה שלו עצמו באתחול. רק נתיב ה-Docker Compose של ה-repo הזה עצמו (`AGENTMEMORY_USE_DOCKER=1`, או חידוש מנוע שהופעל כך) מקשר את `iii-config.docker.yaml` לקריאה-בלבד ולא מרנדר לעולם; `agentmemory start` מזהיר כשהוא מגלה את הצירוף הזה. החליפו את הקובץ הזה ביד, בעקבות אותו מבנה `name: redis` / `config: redis_url: ...` שמוצג בתיעוד ה-workers של [iii-state](https://workers.iii.dev/workers/iii-state) ו-[iii-stream](https://workers.iii.dev/workers/iii-stream), והפנו את `redis_url` ל-Redis נגיש מה-container. `docker-compose.yml` מעביר את `AGENTMEMORY_REDIS_URL` לתוך container המנוע, כך ש-`redis_url: '${AGENTMEMORY_REDIS_URL}'` עובד שם ושומר את ה-URL מחוץ לקובץ המקושר.
התצורה המרונדרת שומרת את ה-URL מחוץ ל-`~/.agentmemory/data/iii-config.runtime.yaml`, אבל ה-worker של התצורה של המנוע עצמו עדיין שומר באופן קבוע את הערך *המורחב* ל-`~/.agentmemory/config/iii-state.yaml` ול-`iii-stream.yaml` ברגע שהוא עולה (ה-הרחבה של `${VAR}` ב-iii-engine קורית לפני שה-worker הזה שומר את ה-seed שלו, והוא שומר את הערך שנפתר, לא את ה-reference). התייחסו לתיקייה הזו כמחזיקה credential: `chmod 700 ~/.agentmemory` בכל host משותף, והעדיפו משתמש ACL של Redis שמוגבל-תחום למה ש-agentmemory צריך על פני ה-credentials המנהליים של ה-database.
**מיגרציה היא לא אוטומטית.** החלפת `AGENTMEMORY_STATE_BACKEND` מתחילה ממאגר ריק בשני הצדדים; שום דבר לא מעתיק נתונים קיימים מ-file ל-Redis או חזרה. ייצאו מה-backend שאתם עוזבים וייבאו לזה שאתם עוברים אליו. זה רץ זהה תחת bash ו-zsh (כולל `bash -u`). מערך כמו `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` לא: zsh משאיר את ה-header כמילה מעוותת אחת במקום ש-bash מפצל אותה לשתיים, כך ששתי הבקשות מקבלות 401 תמיד כש-`AGENTMEMORY_SECRET` מוגדר:
```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` גם מקבל `?maxSessions=` ו-`?offset=` לחלוקה (chunking) של קורפוס גדול על פני כמה קריאות; `strategy` בייבוא הוא `merge` (בטוח כברירת מחדל), `replace`, או `skip`.
### מה iii מחליף
| ערימה מסורתית | agentmemory משתמש ב |
|---|---|
| Express.js / Fastify | iii HTTP Triggers |
| SQLite / Postgres + pgvector | iii KV State + אינדקס וקטורי בזיכרון |
| SSE / Socket.io | iii Streams (WebSocket) |
| pm2 / systemd | פיקוח (supervision) workers של מנוע iii |
| Prometheus / Grafana | iii OTEL + מוניטור health |
| מערכות plugin מותאמות אישית | `iii worker add ` |
**219 קבצי מקור · ~52,000 LOC · 2,500+ בדיקות · 311 פונקציות · 60 תחומי KV**, הכול על שלושה primitives. אין `agentmemory plugin install`. מערכת ה-plugin היא iii עצמו.
---
### ספקי LLM
agentmemory מגלה ספקים אוטומטית מהסביבה שלכם. ספק מאפשר פעולות מגובות-LLM, אבל תצורת ספק בלבד לא מפעילה דחיסת תצפיות בכתיבת LLM. הנתיב הזה דורש גם ספק וגם `AGENTMEMORY_AUTO_COMPRESS=true`.
| ספק | תצורה | הערות |
|----------|--------|-------|
| **No-op (ברירת מחדל)** | לא נדרשת תצורה | דחיסה/סיכום מגובי-LLM מושבתים. דחיסה סינתטית ושליפת BM25 עדיין עובדים. ראו `AGENTMEMORY_ALLOW_AGENT_SDK` מתחת אם הייתם רגילים להסתמך על ה-fallback של מנוי Claude. |
| Anthropic API | `ANTHROPIC_API_KEY` | חיוב לפי טוקן |
| MiniMax | `MINIMAX_API_KEY` | תואם-Anthropic |
| Gemini | `GEMINI_API_KEY` | מפעיל גם embeddings |
| OpenRouter | `OPENROUTER_API_KEY` | כל מודל |
| OpenAI API | `OPENAI_API_KEY` | ברירת מחדל `gpt-5.6-luna`, override עם `OPENAI_MODEL` |
| **מקומי (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. עלות אפס, רץ על החומרה שלכם. ראו [מודלים מקומיים](#local-models-ollama--lm-studio--vllm) מתחת. |
| fallback למנוי Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | opt-in בלבד. יוצר sessions של `@anthropic-ai/claude-agent-sdk`; זה היה גורם לרקורסיה לא חסומה של Stop-hook, אז זה כבר לא ברירת המחדל. |
### מודלים מקומיים (Ollama / LM Studio / vLLM)
agentmemory מדבר עם כל שרת תואם-OpenAI-API, כך שכל דבר שחושף `/v1/chat/completions` עובד בלי שינויי קוד. בלי מפתחות בתשלום, בלי cloud, בלי rate limits; רץ כולו על החומרה שלכם.
**Ollama** (port ברירת מחדל `11434`):
```bash
ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
ollama serve
```
```env
# ~/.agentmemory/.env
OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=qwen3:8b
```
**LM Studio** (port ברירת מחדל `1234`):
פתחו את LM Studio → לשונית Local Server → Start Server. בחרו כל chat model מהבורר (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` לשם שהשרת שלכם יקבל.
**בחירת מודל לעבודת זיכרון**: דחיסה וסיכום הן משימות קצרות (<2K טוקנים בכניסה, <500 טוקנים בפלט) שבהן מודל instruct בגודל 7B מספיק בהחלט. המלצות:
| מודל | גודל | למה |
|-------|------|-----|
| `qwen3:8b` | ~5.2 GB | ברירת מחדל מאוזנת במכונה בת 16 GB; חזק בחילוץ ובטקסט בצורת tool |
| `qwen3:4b` | ~2.6 GB | האפשרות הקטנה הסבירה ביותר; בסדר לדחיסה, חלש יותר לחילוץ גרף |
| `qwen3-coder:30b` | ~19 GB | הבחירה המקומית הטובה ביותר ל-sessions בצורת קוד (30B MoE, 3.3B פעיל) על חומרה בת 24-32 GB |
| `gpt-oss:20b` | ~14 GB | מודל כללי חזק שמתאים ל-16 GB RAM |
| `deepseek-r1:8b` | ~5.2 GB | distill הסקתי (reasoning); יותר איטי אבל חילוצים נקיים יותר |
מודלים של Qwen 3 חושבים כברירת מחדל ויכולים לשרוף את כל תקציב הטוקנים על reasoning לפני כל פלט. הגדירו `AGENTMEMORY_LLM_NOTHINK=1` כדי להוסיף `/no_think` ל-prompts של חילוץ גרף, והעלו את `MAX_TOKENS` (16384 עובד) אם חילוצים חוזרים ריקים.
מודלים ממחלקת reasoning (בסטייל `o1` עם בלוקי ``) יכולים להחזיר `content` ריק עם שדה `reasoning` שהשרת המקומי שלכם אולי לא חושף. אם חילוצים חוזרים ריקים, עברו קודם למודל שאינו reasoning. משתנה הסביבה `OPENAI_REASONING_EFFORT=none` יכול גם להשבית thinking במודלי thinking של Ollama Cloud שמשקפים את schema ה-reasoning של OpenAI.
embeddings מקומיים נשלחים כתלות אופציונלית אבל לא מופעלים כברירת מחדל. הגדירו `EMBEDDING_PROVIDER=local` כדי להפעיל את `Xenova/all-MiniLM-L6-v2` (384 מימדים). בקשת ה-embedding הראשונה מורידה את המודל; ההסקה רצה במכשיר עצמו לאחר מכן. בלי ההגדרה הזו או מפתח embedding מרוחק, הווקטורים נשארים מושבתים, `mem::search` משתמש ב-BM25, ו-`smart-search` יכול עדיין להוסיף התאמות גרף קיימות.
### בחירת מודל מודעת-עלות
כשדחיסת רקע בכתיבת LLM מופעלת עם גם ספק וגם `AGENTMEMORY_AUTO_COMPRESS=true`, היא רצה על כל תצפית, כך שבחירת המודל משנה באופן משמעותי את ההוצאה החודשית. נתוני עומס-עבודה שנלכדו: 635 בקשות / 888K טוקנים / 35 שעות של שימוש פעיל, רצו מול שלושה מודלים של OpenRouter בתמחור מתאריך 2026-05-23.
| שכבה | מודל | קלט / 1M | פלט / 1M | עלות ל-35 השעות שנלכדו | הערות |
|------|-------|------------|-------------|---------------------------|-------|
| מומלץ | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (מוערך) | DeepSeek העדכני ביותר; הבחירה המומלצת הזולה ביותר לעומסי דחיסה. |
| מומלץ | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | איכות דחיסה + סיכום סולידית במחיר נמוך בכ-10× מ-Sonnet. |
| מומלץ | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | reasoning קוד חזק אם ה-sessions שלכם בעיקר בצורת קוד. |
| פרימיום | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (מוערך) | אותו מחיר מחירון כמו ההרצה הנמדדת של Sonnet 4.6; תמחור היכרות $2/$10 עד 2026-08-31. |
| פרימיום | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (מוערך) | שכבת flagship; יקר לעבודת רקע תמידית. |
| הימנעו | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (מוערך) | מודל ממחלקת flagship; overspend לדחיסה. |
שורות נמדדות מגיעות מההרצה שנלכדה; שורות (מוערך) מקנות קנה מידה (scale) לאותו mix טוקנים לפי מחיר המחירון של כל מודל.
agentmemory מדפיס אזהרת runtime כש-`OPENROUTER_MODEL` מתאים לתבנית שכבת-פרימיום. הגדירו `AGENTMEMORY_SUPPRESS_COST_WARNING=1` להשתיק אחרי שעשיתם בחירה מיודעת.
trade-off איכות לעומת עלות לעבודת זיכרון: דחיסה היא משימת סיכום עם סף איכות יחסית רפוי (הסוכן קורא מחדש את הסיכום, לא המשתמש). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder נוחתים בטווח שגיאת עיגול מ-Sonnet במשימה הזו בעוד שהם עולים 10-70× פחות. שמרו את המודלים משכבת-הפרימיום לשאילתות שאתם קוראים ישירות.
מקורות: [תמחור OpenRouter ל-Claude Sonnet 5](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/).
### זיכרון multi-agent (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
בהקמות multi-agent שבהן כמה תפקידים חולקים שרת agentmemory אחד (architect / developer / reviewer / researcher / support-agent), `AGENT_ID` מתייג כל כתיבה בתפקיד שביצע אותה. `AGENTMEMORY_AGENT_SCOPE` קובע אם השליפה מסננת לפי התג הזה.
```env
TEAM_ID=company
USER_ID=engineering-team
AGENT_ID=architect
AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
```
שני מצבים:
| מצב | מתייג כתיבות | מסנן שליפה | מתי להשתמש |
|------|------------|---------------|-------------|
| `shared` (ברירת מחדל) | כן | לא | הקשר בין-סוכנים עם audit trail. ה-architect יכול לראות מה ה-developer ציין, אבל כל שורה רושמת מי אמר את זה. |
| `isolated` | כן | כן | הפרדה מחמירה. ה-architect לעולם לא רואה את התצפיות / הזיכרונות / ה-sessions של ה-developer. |
מה מתויג כש-`AGENT_ID` מוגדר: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. התפקיד זורם מ-`api::session::start` → `mem::observe` → `mem::compress` → KV.
מה מסונן במצב isolated: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. כל endpoint מקבל `?agentId=` לבצע override לפי-בקשה, ו-`?agentId=*` לפרוש כליל מתחום הסביבה. `/memories` מקבל גם `?includeOrphans=true` כדי להציג זיכרונות מלפני-AGENT_ID שה-`agentId` שלהם לא מוגדר.
override לפי-קריאה בשכבת SDK / REST: כל endpoint משנה (`/session/start`, `/remember`) מקבל שדה `agentId` בגוף הבקשה שגובר על הסביבה. שימושי ל-runtimes שמנתבים הרבה תפקידים דרך תהליך שרת אחד. הכלי `memory_save` של MCP חושף את אותו שדה `agentId`, שרת ה-stdio העצמאי מעביר גם `agentId` וגם `project`, וזיכרונות שנשמרו נושאים `agentId` לתוך אינדקס החיפוש, כך שחיפוש בתחום-סוכן מכסה גם זיכרונות וגם תצפיות.
כש-`AGENT_ID` לא מוגדר, הזיכרון נשאר בלי-תחום (unscoped) (התנהגות legacy, בלי תגים, בלי סינונים).
### פורטים
agentmemory + iii-engine נקשרים לארבעה ports כברירת מחדל. אם הפעלה מחדש נכשלת עם `port in use`, הטבלה הזו אומרת לכם לאיזה תהליך לחפש.
| Port | תהליך | מטרה | override של משתנה סביבה |
|------|---------|---------|--------------|
| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
| `3112` | iii-engine | worker סטרימינג פנימי (נצרך על ידי agentmemory + המציג) | `III_STREAM_PORT` (מועדף) או ה-legacy `III_STREAMS_PORT` |
| `3113` | agentmemory | מציג בזמן אמת (`http://localhost:3113`) | `III_VIEWER_PORT` או `AGENTMEMORY_VIEWER_URL` ל-URL המדווח |
| `49134` | iii-engine | WebSocket; workers נרשמים כאן, טלמטריית OTel זורמת מעליו | `III_ENGINE_PORT` או `III_ENGINE_URL` |
`--port ` משנה את העוגן (anchor) של REST ומגזיר ממנו streams ב-`N+1`, מציג ב-`N+2`, ו-WebSocket של המנוע ב-`N+46023`, רק במקום שבו ה-port או ה-URL המפורש המתאים שלמעלה לא מוגדר. זה לא יוצר namespace מבודד למחזור חיים. השתמשו ב-`--instance 1` ל-daemon שני; הוא משתמש בעוגן 3211, ברירת מחדל `3211/3212/3213/49234`, ומקבל תיקיית data ומחזור-חיים נפרדת `instance-1`. Instances 1 עד 50 הולכים לפי אותה תבנית.
המנוע הנעוץ מתחיל עם `--no-update-check` (בלי בדיקות עדכון או security-advisory מול GitHub באתחול) ועם הטלמטריית השימוש האנונימית של iii כבויה: agentmemory מגדיר `III_TELEMETRY_ENABLED=false` למנוע שהוא יוצר אלא אם אתם מייצאים (export) את המשתנה בעצמכם, וקובץ ה-compose המצורף עושה את אותו דבר.
ניקוי תהליכים תקועים (stale) כש-ports נשארים קשורים אחרי הרצה שקרסה:
```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` אוסף (reaps) בצורה נקייה גם את ה-worker וגם את pidfile המנוע ב-shutdown מקורי (native) מסודר. במצב Docker הוא מרוקן את ה-worker המקורי, עוצר את ה-container המדויק של המנוע שאומת, ושומר גם את ה-container וגם את ה-mount שלו ב-`/data` להפעלה מחדש בלי אובדן; ההפעלה הבאה מאמתת ומחדשת את אותו container. הסרת התקנה מבוססת-Docker דורשת `agentmemory remove --keep-data`: היא מסירה קבצים משותפים שמנוהלים על ידי agentmemory בזמן שהיא משמרת את ה-container שאומת, את ה-mount של הנתונים שלו, ואת רשומת מחזור-החיים הנחוצה כדי לשחזר אותם. מחיקת נתוני Docker הרסנית מושארת בכוונה למפעיל אחרי backup. ה-CLI גם מסרב לאמץ או לאותת ל-port holders של Docker או VM (Docker backend, vpnkit, colima) כמנוע native אלא אם `--force` מועבר. הניקוי הידני שלמעלה הוא רק למקרה של אחרי-קריסה שבו לא נשאר שום pidfile.
### קובץ תצורה
שימו את תצורת ה-runtime של agentmemory ב-`~/.agentmemory/.env` במקום לייצא (export) משתנים בכל shell. אם המציג מציג רמז הקמה כמו `export ANTHROPIC_API_KEY=...`, העתיקו אותו לקובץ הזה כ-`ANTHROPIC_API_KEY=...` בלי ה-prefix `export`, ואז הפעילו מחדש את agentmemory.
משתני סביבת התהליך עדיין עובדים וגוברים על ערכים בקובץ.
ב-Windows, אותו קובץ נמצא ב-`%USERPROFILE%\.agentmemory\.env`:
```powershell
New-Item -ItemType Directory -Force $HOME\.agentmemory
notepad $HOME\.agentmemory\.env
```
כדי לבדוק עם מנוי Claude Code Pro/Max במקום מפתח API, בצעו opt-in באופן מפורש:
```env
AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true
```
דחיסת תצפיות בכתיבת LLM דורשת את שתי השורות: גישה לספק LLM (כולל ה-fallback המפורש הזה של מנוי) וגם `AGENTMEMORY_AUTO_COMPRESS=true`. ספק בלבד משאיר את נתיב הדחיסה הסינתטית של ברירת המחדל במקום.
קונסולידציה (nodes של גרף, lessons, crystals) פעילה כברירת מחדל בכל פעם שספק LLM מוגדר. עשו opt-out מפורש עם `CONSOLIDATION_ENABLED=false` אם אתם רוצים פעולה בלי LLM. חילוץ גרף הוא דגל נפרד:
```env
GRAPH_EXTRACTION_ENABLED=true
# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
```
### משתני סביבה
צרו `~/.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
```
---
138 endpoints בפורט `3111`. ה-REST API נקשר ל-`127.0.0.1` כברירת מחדל. endpoints מוגנים דורשים `Authorization: Bearer `, ו-endpoints של mesh sync דורשים `AGENTMEMORY_SECRET` מוגדר באופן מפורש בשני ה-peers.
**אימות (Authentication) פעיל כברירת מחדל.** כש-`AGENTMEMORY_SECRET` לא מוגדר (ב-shell או ב-`~/.agentmemory/.env`), השרת מייצר secret אקראי בהפעלה הראשונה ושומר אותו ב-`~/.agentmemory/secret` במוד `0600`. כל לקוח מצורף קורא אותו משם כשהוא מדבר עם שרת מקומי: ה-CLI, המציג, ה-hooks תחת `plugin/scripts`, שרת ה-MCP וה-shim `@agentmemory/mcp`, התצורות שנכתבות על ידי `agentmemory connect`, והאינטגרציות המצורפות של OpenCode, Pi, OpenClaw, Hermes וה-filesystem-watcher. ה-secret המאוחסן נשלח רק ל-URLs של loopback (`localhost`, `127.0.0.0/8`, `::1`). `AGENTMEMORY_SECRET` מפורש גובר תמיד, ולקוחות מרוחקים עדיין צריכים אותו מוגדר. Docker וה-entrypoints של `deploy/` כבר מייצרים ומייצאים את ה-secret שלהם. כדי לקרוא ל-API ביד:
```bash
curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
```
**כללי בקשה לכתיבות.** בקשות `POST`, `PUT`, `PATCH` ו-`DELETE` ל-REST API ולמציג חייבות לשלוח `Content-Type: application/json` (פרמטר `charset` זה בסדר) בכל פעם שהן נושאות גוף, וכותרת `Origin`, כשהיא קיימת, חייבת להיות origin מסוג loopback לפורט ה-REST או המציג המוגדר, או להיות רשומה ב-`VIEWER_ALLOWED_ORIGINS` (מופרד בפסיקים, למשל `https://memory.example.com`). לקוחות שלא שולחים כותרת `Origin` (CLI, hooks, MCP, curl, server-to-server) לא מושפעים. המציג גם מקבל את ה-origin שלו עצמו.
**Paths של קבצים.** endpoints שקוראים או כותבים קבצים (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) מקבלים רק paths תחת `~/.agentmemory`, תיקיית הנתונים של ה-instance, או תיקייה רשומה ב-`AGENTMEMORY_IMPORT_ROOT` (הפרידו כמה עם `:`, או `;` ב-Windows). `/replay/import-jsonl` מקבל גם את ברירת המחדל שלו `~/.claude/projects`. `/obsidian/export` נשאר בתוך `AGENTMEMORY_EXPORT_ROOT` ו-`/migrate` בתוך `~/.agentmemory`. symlinks נפתרים לפני כל בדיקה.
**ניקוי secrets (scrubbing).** מפתחות API, bearer tokens, בלוקי מפתח פרטי PEM, ו-credentials מוטבעים ב-URLs (`scheme://user:password@host`) מנוקים (redacted) לפני שהטקסט נשמר, בכל נתיב כתיבה: תצפיות, remember, evolve, slots, lessons, actions, sketches, signals, checkpoints, imports, replay של jsonl, mesh sync, שיתופי צוות, פלט דחיסה וסיכום, crystals ו-nodes של גרף.
endpoints מרכזיים
| שיטה (Method) | נתיב | תיאור |
|--------|------|-------------|
| `GET` | `/agentmemory/health` | בדיקת health (ציבורי תמיד) |
| `GET` | `/agentmemory/status` | מה לא תקין ואיך לתקן את זה (HTML לדפדפנים, JSON אחרת) |
| `GET` | `/agentmemory/viewer/snapshot` | כל מה שהמציג מציג, בתגובה אחת |
| `POST` | `/agentmemory/session/start` | התחלת session + קבלת הקשר |
| `POST` | `/agentmemory/session/end` | סיום session |
| `POST` | `/agentmemory/observe` | לכידת תצפית (ראו capture delivery מתחת) |
| `GET` | `/agentmemory/capture` | inbox לכידה, dead letters, ו-spool offline |
| `POST` | `/agentmemory/capture/retry` | ניסיון חוזר ללכידות dead-letter |
| `POST` | `/agentmemory/capture/drain` | שליחת ה-spool המקומי offline עכשיו |
| `POST` | `/agentmemory/smart-search` | חיפוש היברידי |
| `POST` | `/agentmemory/context` | יצירת הקשר |
| `POST` | `/agentmemory/remember` | שמירה לזיכרון ארוך-טווח |
| `POST` | `/agentmemory/forget` | מחיקת תצפיות |
| `POST` | `/agentmemory/enrich` | הקשר קובץ + זיכרונות + bugs |
| `GET` | `/agentmemory/profile` | פרופיל פרויקט |
| `GET` | `/agentmemory/export` | ייצוא כל הנתונים |
| `POST` | `/agentmemory/import` | ייבוא מ-JSON |
| `POST` | `/agentmemory/graph/query` | שאילתת גרף ידע |
| `POST` | `/agentmemory/graph/compact` | גיזום provenance גרף שגדל יותר מהמידה |
| `POST` | `/agentmemory/team/share` | שיתוף עם הצוות |
| `GET` | `/agentmemory/audit` | audit trail |
רשימת endpoints מלאה: [`src/triggers/api.ts`](../src/triggers/api.ts)
**מסירת לכידה (capture delivery).** hooks שולחים כל תצפית פעם אחת ל-`POST /agentmemory/observe` עם `eventId`. זה המזהה של ה-host עצמו לקריאה כשה-payload כולל אחד (למשל `tool_use_id` של Claude Code), אחרת hash של ה-session, סוג ה-hook, שם ה-tool, קלט, פלט, וחותמת הזמן של ה-host. השרת כותב את האירוע ל-inbox לכידה ב-state store, שומר את התצפית, ואז מסיר את רשומת ה-inbox. קוד הסטטוס אומר מה קרה:
| Status | שדה `status` | משמעות |
|---|---|---|
| `201` | `accepted` | נשמר. `observationId` הוא התצפית החדשה. |
| `202` | `accepted` (`state: "retrying"`) | התקבל, אבל השמירה נכשלה. השרת מנסה שוב, גם אחרי הפעלה מחדש. |
| `200` | `duplicate` | ה-`eventId` הזה התקבל כבר. `observationId` הוא התצפית הקיימת; שום דבר חדש לא נשמר. |
| `400` / `422` | `rejected` | payload לא תקין, או שהשמירה נכשלה לחלוטין (האירוע נשמר כ-dead letter). |
| `503` | `rejected` (`retryable: true`) | ה-inbox מלא (`AGENTMEMORY_CAPTURE_INBOX_MAX`). hooks שומרים את האירוע ב-spool ושולחים אותו אחר כך. |
אירועים שנכשלים מקבלים ניסיון חזרה כל `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 שניות) עם backoff מכפיל, עד `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). אירועים שעדיין נכשלים נשארים ב-inbox כ-dead letters, רשומים ב-`/agentmemory/status` ובעמוד ה-Health של המציג, וניתן לנסות אותם שוב עם `POST /agentmemory/capture/retry` (`{"eventId": "..."}` או `{"all": true}`). מזהי אירועים שהתקבלו נזכרים למשך `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 שעות, לכל היותר `AGENTMEMORY_CAPTURE_EVENTS_MAX` מזהים), כך ש-hook שעובר replay אחרי timeout או הפעלה מחדש נשמר פעם אחת, בעוד ששתי קריאות tool נפרדות עם מזהי host משלהן נשמרות פעמיים גם אם התוכן שלהן זהה. כשתצפית נמחקת (forget, מחיקת session, eviction, שכחה אוטומטית, או ייבוא שמחליף את המאגר), האירוע שלה מסומן כנמחק לפני שהתצפית מוסרת, כך ש-replay של אותו אירוע באותו חלון נענה כ-duplicate ולא שומר שום דבר. ה-state store כותב לדיסק כל 2 שניות, כך שאירוע שנענה יכול עדיין להיות רק בזיכרון לרגע. כדי לכסות את זה, כל תשובת `2xx` נושאת גם את `bootId` של השרת (חדש בכל הפעלה), `acceptedAt`, ו-`durableAfterMs` (מרווח השמירה בתוספת 1.5 שניות במאגר הקבצים, 1.5 שניות ב-redis, שם ה-persistence היא הגדרת המפעיל). hooks שומרים את האירוע ב-spool המקומי עד שהחלון הזה עובר ומוחקים אותו בקריאה מאוחרת יותר בלי בקשה נוספת. אם `bootId` השתנה עד אז, השרת הופעל מחדש, אז ה-hook שולח את האירוע שוב עם אותו `eventId`; אירוע שהגיע לדיסק לא נשמר פעמיים. השרת גם שולח אירועים כאלה בעצמו בהפעלה ובכל מרווח ניסיון חזרה, כך שהפעלה מחדש לא מפסידה כלום גם כשאף hook לא רץ אחרי כן. hooks ישנים מתעלמים מהשדות הנוספים, ו-hooks חדשים מול שרת ישן מוחקים את האירוע ב-`2xx` כמו קודם.
כשהשרת נפול, לא עונה בזמן, או מחזיר 5xx, ה-hook מוסיף את התצפית לקובץ spool מקומי, `/capture-spool/-.jsonl` (override לתיקייה עם `AGENTMEMORY_CAPTURE_SPOOL_DIR`). הקובץ פרטי למשתמש שלכם (מוד 600), secrets מנוקים באותו אופן שבו השרת מנקה אותם, הוא מחזיק לכל היותר `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) ומפיל רשומות ישנות מ-`AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). כשהוא מלא, רשומות חדשות נופלות ונספרות, ו-`/agentmemory/status` מדווח על זה. ה-hook עדיין יוצא עם 0 בתוך מגבלת הזמן שלו ולא מוסיף בקשה כשהשרת תקין. ה-spool נשלח בהפעלה הבאה ועל ידי ה-hook הראשון שמגיע לשרת שוב, בתהליך רקע כך שהסוכן לא מחכה. מזהי אירועים מבטיחים שזה בטוח: תצפית שהגיעה לפני timeout לא נשמרת פעמיים. `npx @agentmemory/agentmemory capture` מציג את ה-spool ואת ה-inbox של השרת, `--drain` שולח את ה-spool עכשיו, ו-`GET /agentmemory/capture` מחזיר את אותו הדבר כ-JSON. הגדירו `AGENTMEMORY_CAPTURE_SPOOL=false` כדי לכבות את ה-spool.
**דחיסת provenance של הגרף.** כל node ו-edge בגרף הידע שומר את המזהים של 32 התצפיות החדשות ביותר שהוא בא מהן. מאגרים שנכתבו לפני המכסה הזו יכולים להחזיק אלפי מזהים לכל node חם, מה שמאטה את חיפוש הגרף ואת המציג או מפיל את ה-worker. agentmemory מתקן את זה בעצמו: בהפעלה הראשונה אחרי שדרוג הוא גוזם כל node, edge, edge שהוחלף (היסטוריית הגרף הטמפורלית), וה-snapshot שבמטמון למכסה ברקע, בפרוסות קטנות עם הפסקה ביניהן, כך שחיפוש, לכידה, והמציג ממשיכים לעבוד. הוא שומר את ההתקדמות שלו, ממשיך אחרי הפעלה מחדש, ולעולם לא רץ שוב ברגע שהוא סיים. `/agentmemory/status` ועמוד ה-Health של המציג מציגים את זה כ-pending, running (עם ה-scope והמיקום הנוכחיים), done, או failed. הגדירו `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` כדי לכבות את זה.
כדי להריץ את זה ביד, קראו ל-`POST /agentmemory/graph/compact`. זה הולך על אינדקסי ה-name וה-edge-key במקום לרשום כל node ו-edge, ובטוח להריץ מחדש. כשזה גוזם מזהים זה כותב רשומת audit מסוג `graph_compact`.
```bash
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
```
על מאגר גדול, או כשהקריאה מחזירה 504, הריצו את זה בפרוסות. שלחו `scope` (`nodes`, `edges`, או `history`), `offset`, ו-`limit`, ואז קראו שוב עם `nextOffset` שהוחזר עד שהוא `null`. עשו את זה ל-`nodes`, `edges`, ו-`history`, וסיימו עם קריאה אחת של `{"scope":"snapshot"}`, כי הרצה בפרוסות לא נוגעת ב-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`, מעטפת `sh` תואמת POSIX, ו-`tar`; Windows מקורי משתמש ב-`iii.exe` הנעוץ הידני, WSL2, או Docker Desktop.
