agentmemory: זיכרון מתמשך לסוכני קוד מבוססי AI

זיכרון מתמשך בין סשנים וסוכני תכנות.
זיכרון מתמשך עבור Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode, וכל לקוח MCP.

🇬🇧 English • 🇨🇳 简体中文 • 🇹🇼 繁體中文 • 🇯🇵 日本語 • 🇰🇷 한국어 • 🇵🇹 Português • 🇧🇷 Português (Brasil) • 🇪🇸 Español • 🇩🇪 Deutsch • 🇫🇷 Français • 🇮🇹 Italiano • 🇳🇱 Nederlands • 🇵🇱 Polski • 🇨🇿 Čeština • 🇷🇴 Română • 🇭🇺 Magyar • 🇬🇷 Ελληνικά • 🇸🇪 Svenska • 🇩🇰 Dansk • 🇳🇴 Norsk • 🇫🇮 Suomi • 🇷🇺 Русский • 🇺🇦 Українська • 🇹🇷 Türkçe • 🇮🇱 עברית • 🇸🇦 العربية • 🇮🇳 हिन्दी • 🇧🇩 বাংলা • 🇵🇰 اردو • 🇹🇭 ไทย • 🇻🇳 Tiếng Việt • 🇮🇩 Bahasa Indonesia • 🇵🇭 Tagalog

rohitg00/agentmemory | Trendshift

מסמך עיצוב: 1.7 אלף כוכבים / 240 forks על ה-gist

ה-gist מרחיב את תבנית ה-LLM Wiki של Karpathy עם ניקוד ביטחון, מחזור חיים, גרפי ידע וחיפוש היברידי: agentmemory הוא המימוש בפועל.

npm version CI License Stars skills.sh installs

54 כלי MCP 12 hooks אוטומטיים 0 מסדי נתונים חיצוניים 5,000+ בדיקות עוברות

הדגמת agentmemory

התקנה • התחלה מהירה • מבחני ביצועים • לעומת מתחרים • סוכנים • איך זה עובד • MCP • מציג • תצורה • API

--- AgentMemory מתעד אירועי סשן נתמכים ומאפשר לחפש החלטות, תיקונים ולקחים בין סוכנים. בממשק הצפייה אפשר לעיין בזיכרונות, לערוך, לייצא ולמחוק אותם. חיפוש מילות מפתח עובד ללא מפתח API; embeddings מוסיפים חיפוש סמנטי. ## התקנה דרישות: - Node.js 20 ואילך עם npm ו-npx (`node -v`, `npm -v`, ו-`npx -v`). - ב-macOS/Linux נדרשים גם `curl`, מעטפת POSIX `sh` ו-`tar` להגדרה אוטומטית של הסביבה. - ב-Windows השתמשו ב-WSL2 או ב[הוראות ההתקנה המקורית ל-Windows](#windows). פקודת ההתקנה הראשונית הקנונית: ```bash npx -y @agentmemory/agentmemory@latest ``` בחרו סוכנים וספק, או מצב ללא מפתח. האשף שומר את ההגדרות, מפעיל את שרת הזיכרון ומציע התקנה גלובלית של `agentmemory`. הדגל `-y` מאשר את בקשת npm; `@latest` בוחר את הגרסה הנוכחית. דחיסה באמצעות 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`; לאחר ההורדה הראשונית, ההסקה רצה מקומית. ה-API זמין ב-`http://localhost:3111` וממשק הצפייה ב-`http://localhost:3113`. שניהם מאזינים כברירת מחדל רק לחיבורים מקומיים. ההגדרות נמצאות ב-`~/.agentmemory/.env`; [אחסון הנתונים](#data-storage) מתאר תיקיות זיכרון ומופעים נפרדים. לאחר מכן, הדגימו ששליפה עובדת ותנו לסוכן שלכם את ה-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 `. ראו [אינטגרציות](#works-with-every-agent) ו[פקודות יומיומיות](#everyday-commands).
התקנה גלובלית / 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`).
---

עובד עם כל סוכן

agentmemory עובד עם כל סוכן שתומך ב-hooks, ב-MCP, או ב-REST API. כל הסוכנים חולקים את אותו שרת זיכרון.
Claude Code
Claude Code
plugin מובנה + 12 hooks + MCP
Codex CLI
Codex CLI
plugin מובנה + 6 hooks + MCP
GitHub Copilot CLI
GitHub Copilot CLI
MCP + hooks/skills של plugin
Cursor
Cursor
תוסף מובנה + hooks למחזור חיים + MCP
OpenCode
OpenCode
plugin ללכידה + MCP
Devin
Devin
6 hooks + skills + MCP
OpenClaw
OpenClaw
plugin מובנה + MCP
Hermes
Hermes
plugin מובנה + MCP
pi
pi
שליפה מובנית + תיעוד + skills
OpenHuman
OpenHuman
backend מובנה מבוסס Memory trait
Gemini CLI
Gemini CLI
שרת MCP
Antigravity
Antigravity
MCP + hooks
Claude Desktop
Claude Desktop
שרת MCP
Warp
Warp
חיבור + MCP + skills
Zed
Zed
שרת MCP
Cline
Cline
שרת MCP
Continue
Continue
שרת MCP
Droid
Droid
שרת MCP
Kiro
Kiro
שרת MCP
Qwen Code
Qwen Code
שרת MCP
DeepSeek Harness
DeepSeek Harness
תיעוד מובנה + MCP
Roo Code
Roo Code
שרת MCP
Kilo Code
Kilo Code
שרת MCP
Goose
Goose
שרת MCP
Aider
Aider
REST API
Oh My Pi
שליפה מובנית + תיעוד + skills + MCP אופציונלי

עובד עם כל סוכן שמדבר MCP או HTTP. שרת אחד, זיכרונות משותפים בין כולם.

--- ### אחסון נתונים כברירת מחדל הזיכרונות נשמרים מחוץ למאגר הקוד: | פלטפורמה | תיקיית נתונים | |---|---| | macOS | `~/Library/Application Support/agentmemory` | | Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` | | Windows | `%APPDATA%\agentmemory` | מופע 0 משתמש מחדש ב-`./data/state_store.db` קיים. בחרו תיקייה אחרת עם `--data-dir ` או `AGENTMEMORY_DATA_DIR`. שמרו על אותה תיקייה בהפעלה מחדש ובשדרוג. ```bash agentmemory --data-dir ~/.agentmemory-projects/main agentmemory --instance 1 ``` `--instance 1` משתמש בתיקיית המשנה `instance-1`, בפורט API ‏`3211` ובפורט צפייה `3213`. Redis והעברת נתונים מתוארים ב[מדריך האחסון והגיבוי](../docs/reliability/state-storage.md). הערות השחרור העדכניות: [CHANGELOG.md](../CHANGELOG.md). ---

מבחני ביצועים

תוצאות האחזור העדכניות, הגדרות המדדים ושלבי השחזור: [0.9.31 · 2026-10-28 · strict recall-all@5](../docs/benchmarks/2026-10-28-retrieval-evaluation.md) · [eval/README.md](../eval/README.md). ---

לעומת מתחרים

השוואה מעודכנת של מוצרים ואפשרויות פריסה, עם מקורות: [AgentMemory / Mem0 / Supermemory / Zep / Letta / Cognee / claude-mem](../benchmark/COMPARISON.md) · 2026-10-28. ---

התחלה מהירה

### נסו את זה ב-30 שניות ```bash # Terminal 1: start the server npx -y @agentmemory/agentmemory@latest # Terminal 2: seed sample data and see recall in action npx -y @agentmemory/agentmemory@latest demo ``` `demo` מזריע 3 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) אחרי הפעלה מחדש כשהשרת פועל, בדקו תקינות, צפייה ומצב: ```bash curl -fsS http://localhost:3111/agentmemory/livez curl -fsS http://localhost:3111/agentmemory/health curl -fsS -o /dev/null http://localhost:3113/ npx -y @agentmemory/agentmemory@latest status ``` `status` מציג את מצב השרת, הספקים, מצב ה-embeddings, מסירת התצפיות והשחזור. בקשות REST מוגנות דורשות את סוד השרת. השתמשו ב-`AGENTMEMORY_SECRET` שהגדרתם; אחרת טענו את הסוד המקומי שנוצר: ```bash # Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead. read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret" curl -fsS -X POST http://localhost:3111/agentmemory/remember \ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \ -H 'Content-Type: application/json' \ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}' curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \ -H 'Content-Type: application/json' \ -d '{"query":"restart persistence probe","limit":5}' ``` לאחר מכן הריצו `npx -y @agentmemory/agentmemory@latest stop`, הפעילו שוב את הפקודה הקנונית ב-Terminal 1, המתינו ל-`/agentmemory/livez`, וחזרו על החיפוש. ה-probe חייב עדיין להיות מוחזר. אם בחרתם `--data-dir` מותאם אישית, העבירו את אותה תיקייה בהפעלה מחדש. ### פקודות יומיומיות התקנה והגדרה נמצאות ב[התקנה](#install) מעלה (ההרצה הראשונה מדריכה אתכם צעד אחר צעד). ביום-יום: ```bash agentmemory # start the server agentmemory stop # stop it cleanly agentmemory status agentmemory capture agentmemory capture --drain 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 ``` סשנים מיובאים מופיעים ב-Replay לצד הסשנים המקוריים. התמלילים מתווספים לאינדקס ומסומנים במקור `import`; העיבוד יכול גם ליצור גבישי סשן ולקחים. > **שימו לב אם אתם נשענים על `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 ``` הפקודה מעדכנת את הסביבה המקומית ועשויה לשנות תלויות JavaScript בסביבת העבודה הנוכחית. גבו את הנתונים וקראו את [מדריך השדרוג](../docs/upgrades/iii-0.25.md). ### Claude Code (בלוק אחד, הדביקו אותו) ```text Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall. ``` #### Claude Code בלי התקנת ה-plugin (נתיב MCP בלבד) אם אתם מחווטים את שרת ה-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 ``` הפקודה מגדירה את שרת ה-MCP וממזגת את ה-hooks המצורפים לתצורת המשתמש של Claude Code. אם `CLAUDE_CONFIG_DIR` אינו מוגדר, ריק או מכיל רק תווי רווח, היא משתמשת ב-`~/.claude.json` עבור MCP וב-`~/.claude/settings.json` עבור hooks. ערכי תיקייה אחרים משמשים בדיוק כפי שהוזנו, כולל תווי רווח בתחילת הערך ובסופו. כדי להשתמש בתיקייה מותאמת אישית, הגדירו את `CLAUDE_CONFIG_DIR` לאותו ערך שאינו ריק גם עבור הפקודה הזו וגם עבור Claude Code; הקבצים יהיו אז `$CLAUDE_CONFIG_DIR/.claude.json` ו-`$CLAUDE_CONFIG_DIR/settings.json`, בהתאמה. Claude Code חייב לקבל את הערך בסביבת ההפעלה שלו, גם אם המחבר קורא אותו מקובץ `.env` של AgentMemory. צרו את התיקייה המותאמת אישית לפני הפעלת הפקודה; אחרת המחבר מדלג על Claude Code כי הוא לא זוהה. אם הערך ב-shell מכיל רק תווי רווח, הסירו את `CLAUDE_CONFIG_DIR` מהסביבה לפני הפעלת Claude Code כדי שגם הוא ישתמש בפרופיל ברירת המחדל. השתמשו בנתיב מוחלט. נתיבים יחסיים מפוענחים ביחס לתיקיית העבודה, ולכן יש להריץ את שתי הפקודות מאותה תיקייה. פקודות ה-hook משתמשות בנתיבים מוחלטים לתיקיית `plugin/` המצורפת לחבילה המותקנת. הפעילו שוב את הפקודה לאחר שדרוג agentmemory כדי לרענן את הנתיבים. רשומות המשתמש בקובצי התצורה נשמרות; רק רשומות קודמות של 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 המלאה. ### Cursor ```bash agentmemory connect cursor ``` לאחר מכן ב-**Settings → Plugins → Add marketplace** בחרו את תיקיית agentmemory שמכילה את `.cursor-plugin/plugin.json`, הפעילו את התוסף **agentmemory** וטענו מחדש את החלון. התוסף מספק תיעוד מחזור חיים, זיהוי פרויקט לפי סביבת העבודה, skills ו-MCP. הפעילו את ה-hooks של התוסף או hooks ידניים ב-`~/.cursor/hooks.json` כדי למנוע תיעוד כפול. [Cursor](../integrations/cursor/) ### Pi, Oh My Pi, DeepSeek Harness ```bash agentmemory connect pi --with-mcp agentmemory connect omp --with-mcp agentmemory connect dsh --with-hooks ``` בחרו את הפקודה ללקוח שלכם. Pi ו-OMP מתקינים שליפה מובנית, תיעוד, שליחה מחדש לאחר עבודה לא מקוונת ו-skills; הדגל `--with-mcp` מוסיף את כל הכלים. הריצו `/reload` ב-Pi או הפעילו מחדש את OMP, ואז בדקו `/agentmemory-status`. DSH מתקין MCP ואת תוסף התיעוד המצורף; הפעילו מחדש את DSH לאחר החיבור. Pi תומך גם בחבילה הניתנת להתקנה `@agentmemory/pi`. התקנה מקומית וזמינות npm מתוארות ב[מדריך Pi](../integrations/pi/). השתמשו בשיטת התקנה אחת לכל לקוח. [Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
OpenClaw (הדביקו את ה-prompt הזה) ```text Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools: { "mcpServers": { "agentmemory": { "command": "npx", "args": ["-y", "@agentmemory/mcp"], "env": { "AGENTMEMORY_URL": "http://localhost:3111" } } } } Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`. ``` מדריך מלא: [`integrations/openclaw/`](../integrations/openclaw/)
Hermes Agent (הדביקו את ה-prompt הזה) ```text Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools: mcp_servers: agentmemory: command: npx args: ["-y", "@agentmemory/mcp"] memory: provider: agentmemory Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from https://github.com/rohitg00/agentmemory to ~/.hermes/plugins/agentmemory. ``` מדריך מלא: [`integrations/hermes/`](../integrations/hermes/)
### סוכנים אחרים הפעילו את שרת הזיכרון: `npx -y @agentmemory/agentmemory@latest` #### Skills מובנים דרך `npx skills add` 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. ‏Hermes, OpenClaw, Pi ו-Oh My Pi מתקינים כברירת מחדל אינטגרציה מובנית ו-skills; להפעלת MCP השתמשו ב-`--with-mcp`. - `npx skills add rohitg00/agentmemory` מתקין skills לסוכנים שאין להם skills מובנים בחבילה. דלגו על שלב זה עבור Hermes, OpenClaw, Pi ו-Oh My Pi; המחברים שלהם כבר מתקינים את ה-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/` | התוסף מספק hooks למחזור חיים, זיהוי סביבת עבודה, skills ו-MCP ב-Cursor IDE וב-`cursor-agent`. ראו [הגדרת Cursor](#cursor). | | **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 --with-mcp`. שליפה מובנית + תיעוד + skills. `/reload`, `/agentmemory-status`. [Pi](../integrations/pi/). | | **Oh My Pi** | `~/.omp/agent` | `agentmemory connect omp --with-mcp`. שליפה מובנית + תיעוד + skills. [Oh My Pi](../integrations/omp/). | | **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 מותקן, 9 ה-skills של agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) מופיעים באופן מובנה בפלטת פקודות ה-slash של Warp. | | **Cline (CLI)** | `~/.cline/data/settings/cline_mcp_settings.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` קיים. עבור YAML קיים הוא מציג בלוק להוספה תחת `mcpServers:`, כדי לשמור הערות ועוגנים. Continue משתמש במערך ולא באובייקט. | | **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` מפעיל את כלי MCP. הוסיפו `--with-hooks` כדי לטעון את תוסף הלכידה המובנה ב-AgentMemory. אין צורך בחבילת תוסף נפרדת. [DSH](../docs/dsh.md). | | **Goose** | ממשק הגדרות MCP של Goose | אותו בלוק `mcpServers`; השתמשו ב-`goose configure` → Add Extension → MCP. עריכה ישירה של YAML ב-`~/.config/goose/config.yaml` נתמכת אבל ה-schema משתמש ב-`extensions:` + `cmd` (לא `mcpServers:` + `command`). | | **Aider** | n/a | השתמשו ב[דוגמאות REST עם אימות](#validate-a-fresh-install-and-restart-persistence) לשמירה ולחיפוש מתוך סקריפטים. | | **סוכנים נתמכים** | skills בלבד | `npx skills add rohitg00/agentmemory`; בחרו את ה-skills ואת הסוכנים שבהם יותקנו. | **לקוחות MCP ב-sandbox** (Flatpak / Snap / containers מגבילים) שלא יכולים להגיע ל-`localhost` של ה-host: הגדירו גם `"AGENTMEMORY_FORCE_PROXY": "1"` בבלוק ה-`env`, והפנו את `AGENTMEMORY_URL` למסלול שה-sandbox יכול בפועל להגיע אליו (למשל כתובת ה-LAN שלכם). ### גישה פרוגרמטית (Python / Rust / Node) השתמשו ב-[REST API](#api) מכל שפה או ב[כלי MCP](#mcp-server) מתוך סוכן. REST משתמש ב-JSON ובאימות bearer; ראו [דוגמת שמירה וחיפוש](#validate-a-fresh-install-and-restart-persistence). לאינטגרציה ישירה עם סביבת הריצה, ראו [דוגמאות Python](../examples/python/). ### מהמקור (From source) ```bash git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory npm install && npm run build && npm start ``` `npm start` מפעיל את אותו שרת מקומי כמו ה-CLI המותקן. הדרישות מופיעות ב[התקנה](#install); ה-API וממשק הצפייה מאזינים ב-`127.0.0.1`. ### Windows agentmemory פועל ב-Windows 10/11. ‏WSL2 פועל במסלול Linux ויכול להתקין את המנוע הנעוץ אוטומטית. ב-Windows מקורי יש להתקין ידנית את הבינארי הנעוץ iii-engine v0.25.1: הורידו את הארכיון המתאים מ-[דף ההפצה של iii 0.25.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.1), אמתו את ה-checksum והוסיפו את `iii.exe` ל-`PATH` (למשל `%USERPROFILE%\.local\bin\iii.exe`). ה-CLI אינו מחלץ אוטומטית את ZIP של Windows. חיבור MCP אוטומטי ב-Windows מקורי נתמך רק עבור `agentmemory connect copilot-cli`. עבור סוכנים מקומיים אחרים ב-Windows, השתמשו בבלוק MCP הידני מתוך [סוכנים אחרים](#other-agents). הפעילו `connect` בתוך WSL רק אם סוכן היעד מותקן באותה סביבת WSL. **MCP עצמאי בלבד (ללא מנוע).** אם דרושים רק כלי MCP, ללא REST API, מציג או שירותי runtime: ```powershell npx -y @agentmemory/agentmemory@latest mcp # or npx -y @agentmemory/mcp ``` הריצו `agentmemory doctor` או הפעילו מחדש עם `--verbose`. אם הפורטים תפוסים, השתמשו ב-`--port ` או ב-`--instance `. תאימות ושחזור מתוארים ב[מדריך השדרוג](../docs/upgrades/iii-0.25.md). ---

פריסה

לאירוח עצמי השתמשו ב-Docker Compose או בתבניות שלהלן. הזיכרון ופרטי הגישה נמצאים בנפח `/data`; גבו אותו והשתמשו בו מחדש בשדרוג. אימות, רשת, גיבוי והעברה מתוארים ב[מדריך הפריסה](../deploy/README.md).

פרסו ל-fly.io פרסו ל-Railway

כפתור הפריסה בלחיצה אחת של 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 ושל הנתונים. REST משתמש ב-`3111` וממשק הצפייה ב-`3113`. השאירו אותם פרטיים או הגנו עליהם באימות וב-TLS. הגדרות פלטפורמה ו[העברה מ-Docker הישן](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) מתוארות במדריך הפריסה. ---

למה agentmemory

הידע על הפרויקט מתפזר בין שיחות וקובצי הוראות. AgentMemory מאפשר לחפש החלטות, תיקונים ולקחים קודמים מתוך הסוכן שבו משתמשים כעת. ### לעומת זיכרון מובנה בסוכן כל סוכן קוד מבוסס AI נשלח עם זיכרון מובנה: ל-Claude Code יש `MEMORY.md`, ל-Cursor יש notepads, ל-Cline יש memory bank. אלה עובדים כמו פתקיות דביקות. agentmemory הוא מסד הנתונים הניתן לחיפוש שמאחורי הפתקיות הדביקות. | | מובנה (CLAUDE.md) | agentmemory | |---|---|---| | תחזוקה | הוראות שנערכות ידנית | היסטוריית סשנים וזיכרונות עם אינדקס | | חיפוש | טוען הכול להקשר | BM25 + וקטור + גרף (top-K בלבד) | | בין-סוכנים | קבצים לפי סוכן | MCP + REST (כל סוכן) | | תיאום | אין | leases, signals, actions, routines | | Observability | קריאת קבצים ידנית | מציג בזמן אמת בפורט :3113 | ---

איך זה עובד

### צינור הזיכרון ```text PostToolUse hook fires -> Stable event ID / durable capture inbox / offline spool -> Privacy filter (strip secrets, API keys) -> Store raw observation -> Synthetic compression by default (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true) -> Vector embedding when an embedding provider is active -> Index in BM25, plus vectors when enabled Stop / SessionEnd hook fires -> Summarize session -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true) -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true) SessionStart hook fires -> Load project profile (top concepts, files, patterns) -> Hybrid search (BM25 + vector + graph) -> Token budget (default: 2000 tokens) -> Inject context when enabled by the integration ``` ### קונסולידציית זיכרון ב-4 שכבות מבוסס על האופן שבו מוח האדם מעבד זיכרון, כולל קונסולידציה בשינה. | שכבה | מה | אנלוגיה | |------|------|---------| | **עבודה (Working)** | תצפיות גולמיות משימוש בכלים | זיכרון קצר-טווח | | **אפיזודי (Episodic)** | סיכומי session דחוסים | "מה קרה" | | **סמנטי (Semantic)** | עובדות ודפוסים שחולצו | "מה שאני יודע" | | **פרוצדורלי (Procedural)** | workflows ודפוסי החלטה | "איך לעשות את זה" | זיכרונות דועכים (decay) עם הזמן (עקומת Ebbinghaus). זיכרונות שנגישים אליהם לעיתים קרובות מתחזקים. זיכרונות שהתיישנו מתפנים (evict) אוטומטית. סתירות מתגלות ונפתרות. ### מה נלכד הטבלה מתארת את ה-hooks של Claude Code. אינטגרציות אחרות מתעדות אירועים שהלקוח שלהן מספק. הזרקת הקשר אוטומטית דרך ה-hooks המשותפים היא אופציונלית: `AGENTMEMORY_INJECT_CONTEXT=true`. | Hook | מה נלכד | |------|----------| | `SessionStart` | נתיב הפרויקט, מזהה ה-session | | `UserPromptSubmit` | prompts של המשתמש (מסוננים לפרטיות) | | `PreToolUse` | דפוסי גישה לקבצים + הקשר מועשר | | `PostToolUse` | שם ה-tool, קלט, פלט | | `PostToolUseFailure` | הקשר שגיאה | | `PreCompact` | מזריק מחדש זיכרון לפני compaction | | `SubagentStart/Stop` | מחזור חיים של תת-סוכן | | `Stop` | סיכום סוף-session | | `SessionEnd` | סימון השלמת session | ### יכולות מפתח | יכולת | תיאור | |---|---| | **לכידה אוטומטית** | אירועי סשן וכלים נתמכים המתועדים באינטגרציות מובנות | | **חיפוש סמנטי** | 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) מוחרגות מכל נתיב שליפה; שרשרת הגרסאות שומרת את ההיסטוריה שלהן. [0.9.31: `AGENTMEMORY_VECTOR_BACKFILL=all` / `AGENTMEMORY_VECTOR_BACKFILL_MAX`](../docs/reliability/source-and-vector-recovery.md). 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` | חינמי | [`EMBEDDING_PROVIDER=local`](../README.md#embedding-providers) | | 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` | [OpenAI](https://openai.com/api/pricing/) | [text-embedding-3-small](https://platform.openai.com/docs/models/text-embedding-3-small) | | Voyage AI | `voyage-code-3` | בתשלום | מותאם לקוד | | Cohere | `embed-english-v3.0` | ניסיון חינמי | כללי | | OpenRouter | כל מודל | משתנה | proxy מרובה-מודלים | ---

שרת MCP

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`) ואז מחיל אירועים חיים ב-SSE ב-`/agentmemory/viewer/events` על worker ‏REST: זיכרונות, לקחים, תצפיות, רשומות audit, שינויים בגרף ועדכוני health מופיעים ללא polling או טעינת דף מחדש. - **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'`). ---

תצורה

### ספקי 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` יכול עדיין להוסיף התאמות גרף קיימות. ### בחירת מודל מודעת-עלות התחילו ללא מפתח לתיעוד ולחיפוש מילות מפתח. `EMBEDDING_PROVIDER=local` מאפשר חיפוש סמנטי מקומי לאחר הורדת המודל. דחיסת LLM דורשת ספק ו-`AGENTMEMORY_AUTO_COMPRESS=true`; היא עשויה לשלוח בקשה לכל תצפית, לכן בדקו מחירים עדכניים. ממשק הצפייה ו-`agentmemory status` מציגים ספקים פעילים. ### זיכרון 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, בלי תגים, בלי סינונים). ### פורטים | Port | מטרה | משתנה סביבה | |---|---|---| | `3111` | REST API, MCP HTTP ואירועי צפייה בזמן אמת | `III_REST_PORT` | | `3113` | ממשק צפייה | `III_VIEWER_PORT` | `--port ` מגדיר את פורט REST ואת ברירת המחדל של הצפייה ל-`N+2`. `--instance N` יוצר סביבה נפרדת. פורטים פנימיים חייבים להישאר פרטיים; קראו את [מדריך הפריסה](../deploy/README.md) לפני פתיחת גישה מרחוק. ### אחסון: קובץ או Redis אחסון הקבצים המוגדר כברירת מחדל אינו דורש מסד נפרד. Redis אופציונלי עם `AGENTMEMORY_STATE_BACKEND=redis` ו-`AGENTMEMORY_REDIS_URL`. החלפת backend אינה מעתיקה זיכרונות קיימים. התמדה, מגבלות Redis וייצוא/ייבוא עם אימות מתוארים ב[מדריך האחסון](../docs/reliability/state-storage.md). ### קובץ תצורה הגדירו את תצורת זמן הריצה של agentmemory בקובץ `~/.agentmemory/.env` במקום לייצא משתנים בכל shell. אם המַציג מציג הנחיה כמו `export ANTHROPIC_API_KEY=...`, העתיקו לקובץ ללא התחילית `export` ואז הפעילו מחדש את agentmemory. הגדירו `AGENTMEMORY_ENV_FILE` כדי להשתמש בנתיב אחר לקובץ הסביבה. משתני הסביבה של התהליך קודמים לערכי הקובץ. הפעילו מחדש את השרת לאחר שינוי הגדרות. ב-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`. הזרקת הקשר ודחיסה הן אופציונליות; דחיסה דורשת גם ספק. מצב `core` מצמצם את כלי ה-MCP הגלויים: ```env EMBEDDING_PROVIDER=local # AGENTMEMORY_INJECT_CONTEXT=true # AGENTMEMORY_AUTO_COMPRESS=true # AGENTMEMORY_TOOLS=core # AUTO_FORGET_ENABLED=false # LESSON_DECAY_ENABLED=false # INSIGHT_DECAY_ENABLED=false ``` ההפניה המלאה [`.env.example`](../.env.example) כוללת ספקים, מסנני תיעוד, שמירה, אחסון, צוותים ותכונות אופציונליות. `AGENTMEMORY_ENV_FILE` בוחר קובץ אחר. לעולם אל תוסיפו ל-commit קובץ `.env` מלא או סוד bearer. ---

API

147 endpoints בפורט `3111`. ה-REST API נקשר ל-`127.0.0.1` כברירת מחדל. endpoints מוגנים דורשים `Authorization: Bearer `, ו-endpoints של mesh sync דורשים `AGENTMEMORY_SECRET` מוגדר באופן מפורש בשני ה-peers. **אימות (Authentication) פעיל כברירת מחדל.** אם `AGENTMEMORY_SECRET` לא מוגדר, בהפעלה הראשונה ה-CLI יוצר סוד אקראי ב-`~/.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 מלאה: [הפניית REST שנוצרה מהקוד](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
**מסירת לכידה (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 של הגרף.** דחיסת נתוני provenance ישנים נדחית בזמן האתחול, משום שהיא קוראת scopes ישנים בשלמותם. `/agentmemory/status` מציג `deferred`, או `off` כאשר `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. הפעילו את הדחיסה הידנית שלהלן בזמן תחזוקה. העברת אינדקס האחזור היא פעולה נפרדת: השתמשו ב־`agentmemory graph-index migrate --allow-legacy-scan` לפי [מדריך התחזוקה](../docs/reliability/graph-index-migration.md). כדי להריץ את זה ביד, קראו ל-`POST /agentmemory/graph/compact`. זה הולך על אינדקסי ה-name וה-edge-key במקום לרשום כל node ו-edge, ובטוח להריץ מחדש. כשזה גוזם מזהים זה כותב רשומת audit מסוג `graph_compact`. ```bash curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -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 "Authorization: Bearer " -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}' curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"scope":"snapshot"}' ``` ---

פיתוח

```bash npm run dev # Hot reload npm run build # Production build npm test # 5,000+ tests npm run test:integration # API tests (requires running services) ``` הדרישות מופיעות ב[התקנה](#install). כללי התרומה ובדיקות ההפצה נמצאים ב-[CONTRIBUTING.md](../CONTRIBUTING.md).

רישיון

[Apache-2.0](../LICENSE)