Hindsight
זיכרון שלומד, בתוך הסוכן שלך
מה זה Hindsight, איך הוא שונה מחיפוש וקטורי, ואיך מחברים אותו לסוכן ספציפי או לפרויקט ספציפי: Claude Code, MCP ידני, סוכן בפייתון ו-LangGraph. עם פקודות וקוד מהתיעוד הרשמי.
מה זה Hindsight
Hindsight הוא מערכת זיכרון לסוכני AI, קוד פתוח (רישיון MIT) של Vectorize. המטרה שלה מוגדרת בתיעוד כך: סוכן שלומד לאורך זמן, לא רק סוכן שזוכר היסטוריית שיחה. בניגוד לחיפוש וקטורי רגיל, היא מחלצת עובדות, ישויות וקשרים, ומאחדת אותם ל"אמונות" שמתעדכנות כשמגיע מידע חדש.
שלוש פעולות
retain שומר מידע. recall שולף זיכרונות. reflect חושב על הזיכרון ומחזיר תשובה מנומקת.
בנק זיכרון (bank)
מאגר מבודד אחד: למשתמש, לסוכן או לפרויקט. אין דליפה בין בנקים. זה המפתח לשאלה "איך משלבים בסוכן או בפרויקט ספציפי".
ארבעה סוגי זיכרון
עובדות על העולם, חוויות של הסוכן, תצפיות (אמונות מאוחדות עם ראיות) ומודלים מנטליים (תשובה עומדת לשאלה קבועה).
איפה זה רץ
שרת Docker או pip מעל PostgreSQL עם pgvector, Kubernetes, או שירות ענן מנוהל. אפשר גם מצב מקומי מוטמע בלי שרת.
איך הוא חושב: retain, recall, reflect
retain - שמירה
Hindsight משתמש ב-LLM כדי לחלץ מהטקסט עובדות, תאריכים, ישויות וקשרים, ומנרמל אותם. לכן שמירה עולה טוקנים של מודל חילוץ. אפשר להעביר context (על מה זה) ו-timestamp.
recall - שליפה
ארבע אסטרטגיות במקביל: סמנטית (וקטורים), מילות מפתח (BM25), גרף (ישויות, זמן, סיבתיות) וטמפורלית (טווח זמן). התוצאות ממוזגות ומדורגות מחדש, ואז נחתכות לתקציב הטוקנים שביקשת.
reflect - הסקה
לא שליפה אלא חשיבה: "אילו סיכונים פתוחים בפרויקט?", "למה הודעות מסוימות קיבלו תגובה?". התשובה מושפעת מהמשימה ומתכונות האופי של הבנק (ספקנות, דקדקנות, אמפתיה).
תצפיות ומודלים מנטליים
ברקע, עובדות קשורות מתאחדות לתצפיות עם ראיות וספירת הוכחות. מודל מנטלי הוא תשובה קבועה לשאלה ("מה ההעדפות של המשתמש?") שנכתבת מחדש ברקע, וקריאתה היא קריאת מסד נתונים בלי LLM. כך סוכן יכול להתחיל סשן עם דף ידע מוכן.
שלב 1: להרים שרת זיכרון
לפני כל חיבור צריך מקום שבו הזיכרון חי. שלוש אפשרויות מהתיעוד:
Docker (מומלץ בתיעוד)
export OPENAI_API_KEY=sk-xxx
docker run -it --pull always --name hindsight --restart unless-stopped \
-p 8888:8888 -p 9999:9999 \
-e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
-v hindsight-data:/home/hindsight/.pg0 \
ghcr.io/vectorize-io/hindsight:latestה-API יושב על http://localhost:8888 והממשק הגרפי על http://localhost:9999. ספק המודל נקבע ב-HINDSIGHT_API_LLM_PROVIDER. נתמכים מעל 25 ספקים, כולל OpenAI, Anthropic, Gemini, וגם מקומיים כמו Ollama.
בלי שרת: מצב מוטמע בפייתון
pip install hindsight-all -U
import os
from hindsight import HindsightServer, HindsightClient
with HindsightServer(
llm_provider="openai",
llm_model="gpt-5-mini",
llm_api_key=os.environ["OPENAI_API_KEY"],
) as server:
client = HindsightClient(base_url=server.url)
client.retain(bank_id="my-bank", content="Alice works at Google")
print(client.recall(bank_id="my-bank", query="Where does Alice work?"))שירות מנוהל
Hindsight Cloud, בחיוב לפי שימוש עם קרדיט התחלתי. כל לקוח מצביע ל-https://api.hindsight.vectorize.io עם מפתח API. לא נבדק כאן המחיר המדויק, ראו את דף התמחור.
שילוב א: סוכן קוד (Claude Code) בפרויקט ספציפי
זה המסלול הקצר לפרויקט קוד. חבילה אחת, @vectorize-io/hindsight-coding-agents, מחברת את Claude Code, Codex, Cursor, Copilot, opencode ועוד. לכל ריפו נוצר בנק משלו בשם coding-agent::<שם-הריפו>, והוא מוזן אוטומטית מהיסטוריית git וממה שהסוכן עשה בסשנים קודמים.
- התקנה מתוך תיקיית הפרויקט. בלי יעד מפורש הפקודה לא משנה כלום:
cd ~/work/payments-api npx @vectorize-io/hindsight-coding-agents install claude-code - בחירת מקום הזיכרון (נשאל פעם אחת):
cloud, שרת שאתה מריץ, אוdaemonמקומי שדורשuvומפתח LLM לחילוץ. בלי אינטראקציה:npx @vectorize-io/hindsight-coding-agents install claude-code \ --server self-hosted --api-url http://localhost:8888 - מה נכתב: שלושה hooks ב-
~/.claude/settings.json, שרת MCP דרךclaude mcp addברמת משתמש, וסקיל נלווה. אין פקודת הפעלה: ה-hook של תחילת סשן עושה את העבודה. - מגביל לפרויקטים שבחרת בקובץ
~/.hindsight/coding-agent.json. כברירת מחדל כל פרויקט מקבל זיכרון; כך מכבים את זה בכל מקום ומאשרים רק תיקיות מסוימות:{ "optInOnly": true, "optInPaths": ["~/work/payments-api"] } - בנק בשם שאתה קובע לפרויקט (נתיב מוחלט למפה, הקידומת הארוכה מנצחת):
{ "mapPathToBank": { "/Users/me/work/payments-api": "payments-api-prod" }, "retainTags": ["project:{gitProject}"] } - סוכן אחד בלבד: אם רוצים למשל זיכרון כבוי רק ב-Claude Code:
{ "harnesses": { "claude-code": { "disabled": true } } }
מה קורה בפועל
בפתיחת סשן הבנק מוזן מכל הודעות ה-commit וממסמכי שיחה קודמים, ונבנים דפי ידע (מפת רכיבים, מוסכמות, החלטות ונימוקים). בהודעה הראשונה בסשן מוזרק לסוכן תקציר reflect קטן של מה שהפרויקט כבר החליט. אחרי כל תשובה נשמר חלק מהשיחה חזרה לבנק. הסוכן מקבל גם כלי MCP: hindsight_search_knowledge_pages, hindsight_reflect ועוד.
הגדרות שכדאי להכיר
autoInject קובע מה מוזרק: reflect (ברירת מחדל), pages, recall או none. retainExtractionMode קובע עלות: concise הוא ברירת המחדל, verbose יקר פי כמה.
הסרה
npx @vectorize-io/hindsight-coding-agents uninstall claude-code מסיר בדיוק מה שההתקנה הוסיפה, והיא גם גיבתה קבצים שנגעה בהם.
שילוב ב: חיבור ידני דרך MCP, בנק אחד לכל פרויקט
לכל בנק יש נקודת MCP משלו, http://localhost:8888/mcp/{bank_id}/, ולכן הבחירה בבנק היא בחירה בפרויקט: אין צורך שהכלים יקבלו מזהה. במצב בנק יחיד זמינים 27 כלים (זיכרון, מודלים מנטליים, directives, מסמכים, תגיות ועוד). הנקודה פתוחה כברירת מחדל, אלא אם הפעלת מפתח API בשרת.
# Claude Code, בנק לפי כותרת
claude mcp add --transport http hindsight http://localhost:8888/mcp \
--header "Authorization: Bearer your-secret-key" \
--header "X-Bank-Id: payments-api"אותו דבר ב-Claude Desktop, בקובץ ההגדרות:
{
"mcpServers": {
"hindsight": {
"url": "http://localhost:8888/mcp",
"headers": {
"Authorization": "Bearer your-secret-key",
"X-Bank-Id": "payments-api"
}
}
}
}סדר העדיפויות בבחירת בנק: קודם הנתיב ב-URL, אחר כך הכותרת. כדי לקבוע שהסוכן ישמור ויזכור בהתאם לכללים שלך, הוסף הנחיות בשרת עם HINDSIGHT_API_MCP_INSTRUCTIONS, והן יתווספו לתיאורי הכלים retain ו-recall.
שילוב ג: סוכן שאתה כותב בקוד (פייתון)
כאן אתה שולט בדיוק מתי נשמר ומתי נשלף. הדפוס: אתחול בנק עם משימה (mission) ואופי, שליפה לפני כל קריאה למודל, שמירה אחריה.
pip install hindsight-client -U
from hindsight_client import Hindsight
from openai import OpenAI
hs = Hindsight(base_url="http://localhost:8888")
llm = OpenAI()
BANK = "support-agent-acme" # בנק אחד לפרויקט / לקוח
# פעם אחת: יצירת הבנק
hs.create_bank(
bank_id=BANK,
name="Acme support agent",
mission="Support agent for Acme. Track customer issues, decisions and promised follow-ups.",
disposition={"skepticism": 3, "literalism": 3, "empathy": 3},
)
def answer(user_msg: str) -> str:
# 1. שליפה לפני ה-LLM
mem = hs.recall(bank_id=BANK, query=user_msg, max_tokens=2048, budget="mid")
context = "\n".join(f"- {r.text}" for r in mem.results)
# 2. קריאה למודל עם הזיכרון בפרומפט
resp = llm.chat.completions.create(
model="gpt-5-mini",
messages=[
{"role": "system", "content": f"Relevant memory:\n{context}"},
{"role": "user", "content": user_msg},
],
)
reply = resp.choices[0].message.content
# 3. שמירה אחרי
hs.retain(
bank_id=BANK,
content=f"User: {user_msg}\nAgent: {reply}",
context="support conversation",
document_id="conversation_001", # אותו מזהה = עדכון, לא כפילות
retain_async=True,
)
return replyלשאלות שדורשות חשיבה ולא שליפה (למשל "מה פתוח מול הלקוח הזה?") קרא ל-hs.reflect(bank_id=BANK, query=..., budget="low") והשתמש ב-answer.text.
למה בנק לפי פרויקט
הבידוד חזק: אין דליפה בין בנקים. לסוכן שמשרת כמה לקוחות, בנק לכל לקוח הוא הדרך הבטוחה.
הטקסט הוא לא פקודה
זיכרון שנשלף הוא נתון. הכנס אותו לפרומפט כ"הקשר", לא כהוראות, כדי שתוכן שנשמר בעבר לא יכתיב התנהגות.
שילוב ד: LangGraph, או עטיפה של שתי שורות
LangGraph / LangChain
החבילה hindsight-langgraph מציעה שלושה דפוסים: כלים (retain, recall, reflect כ-tools), צמתי גרף שמזריקים זיכרון לפני המודל ושומרים אחריו, ו-BaseStore. בנק לפי משתמש נבחר בזמן ריצה מתוך ה-RunnableConfig.
pip install hindsight-langgraph
from hindsight_client import Hindsight
from hindsight_langgraph import create_hindsight_tools
client = Hindsight(base_url="http://localhost:8888")
tools = create_hindsight_tools(
client=client,
bank_id="user-123",
include_reflect=False, # בלי reflect אם לא צריך
)
# מעבירים את tools ל-create_react_agent או ל-bind_toolsבצמתים: create_recall_node(client=client, bank_id_from_config="user_id") ו-create_retain_node(...). אם Hindsight נופל, הצמתים רושמים לוג ולא מפילים את הגרף.
עטיפת לקוח LLM
הדרך הקצרה לסוכן קיים: מחליפים את הלקוח בעטוף, והזיכרון נשלף ונשמר בכל קריאה.
pip install hindsight-litellm
from openai import OpenAI
from hindsight_litellm import wrap_openai
client = wrap_openai(
OpenAI(),
bank_id="user-123",
hindsight_api_url="http://localhost:8888",
)יש גם wrap_anthropic(). בלי hindsight_api_url העטיפה פונה כברירת מחדל לענן של Hindsight, וזה חשוב אם לא רוצים שהמידע יצא מהמחשב.
רשימת האינטגרציות הרשמית כוללת עוד מסגרות: CrewAI, Pydantic AI, OpenAI Agents SDK, Google ADK, n8n, Zapier, Dify ועוד.
איזה שילוב מתאים למה
| המצב שלך | שילוב | למה |
|---|---|---|
| פרויקט קוד עם Claude Code | א | בנק לריפו, מוזן מ-git, בלי כתיבת קוד |
| סביבה נעולה או סוכן שאינו קוד | ב (MCP ידני) | שינוי הגדרה אחד, בנק לפי כתובת |
| סוכן שנכתב בפייתון/TS | ג | שליטה מלאה במה נשמר ומתי |
| גרף LangGraph קיים | ד | צמתים מוכנים ובנק לפי משתמש |
| רוצה הוכחת היתכנות מהירה | ד (עטיפה) | שתי שורות, בלי שינוי לוגיקה |
איך בודקים שזה עובד
- אחרי ההתקנה פתח סשן חדש, ספר לסוכן החלטה מפורשת ("נעגל רק את הסכום הסופי, לא שורות"), וסגור.
- פתח סשן נוסף באותו פרויקט ושאל מה סוכם. זכור שהעיבוד ברקע, ולכן בשנייה הראשונה אחרי השמירה אולי עוד אין תוצאה.
- פתח את הממשק ב-
http://localhost:9999וחפש את הבנק. אתה אמור לראות עובדות, ישויות ותצפיות. - בשילוב א, הכלי
hindsight_diagnoseמדווח מה הקובץ אומר ומה הלקוח הרץ באמת משתמש בו.
מגבלות ומה לא בדקנו
- העלות היא של מודל החילוץ והאיחוד ברקע, ולא של האחסון. ככל שמשתמשים ב-verbose או שומרים הרבה, היא גדלה.
- הפרסום של Hindsight על דיוק (LongMemEval) הוא מהתיעוד שלהם, ושוחזר לפי הטענה על ידי Virginia Tech ו-Washington Post. לא בדקנו בעצמנו.
- ב-LangGraph BaseStore: הקריאה
getמבוססת recall, ו-deleteאינו מוחק בפועל. זה מתועד. - המדריך נכתב מהתיעוד ולא מהרצה על מחשב. לפני שימוש בפרויקט אמיתי הרץ קודם על ריפו ניסיון.
מקורות
- vectorize-io/hindsight ו-README (גרסה v0.10.2).
- תיעוד Hindsight, Coding Agents, MCP Server, Python SDK, LangGraph, LiteLLM, תוסף Claude Code הישן.
- המאמר ו-benchmarks.