agent-memory

Lokale Langzeitgedächtnis-Infrastruktur (Local Long-Term Memory Infrastructure). Agent-neutral: nicht an ein bestimmtes Agent-Framework gebunden, Anbindung auf drei Wegen——

• Python-Bibliothek: Frameworks wie LangGraph können direkt import agent_memory verwenden (siehe agent_memory/long_term/adapters/);

• MCP-Server: jeder MCP-fähige Client (siehe agent_memory/server/, M2+ Implementierung);

• Skill: als Skill an einen Skill-fähigen Agenten anhängen (siehe skills/agent-memory/, M3 Implementierung).

Anbindungsschritte und Unterstützung der jeweiligen Host-Adapter siehe docs/agent-integration.md (inkl. Checkliste der Host-Runtime-Verantwortlichkeiten).

Aktueller Stand: M7 (abgeschlossen)

M0 liefert nur das Projektskelett und das Kern-Schema:

• agent_memory/models.py: Pydantic-Modelle und Validierungsregeln für Gedächtniseinträge (MemoryEntry), Beweisverweise (EvidenceRef) und Destillationsvorschläge (MemoryProposal);

• agent_memory/config.py: Ein einziges Konfigurationsmodul, durch Umgebungsvariablen überschreibbar, ungültige Konfiguration fail-closed;

• evals/datasets/layer1/: 20 Bewertungsfälle für „Basisabruf" (YAML), für die Abrufbewertung ab M1+.

M1 liefert den Gedächtnis-Kern-MVP (manuelle Destillation): long_term/store/ (Markdown-Gedächtnisschicht + sqlite-vec/FTS5 abgeleitete Indizes), long_term/retrieve/ (bge-m3-Embeddings + dichte/spärliche RRF-Hybridsuche), long_term/ingest/redact.py (Regex-Schwärzung), cli.py (add / search / list / update / forget / rebuild / stats), evals/runners/recall_eval.py (layer1 recall@5).

M2 liefert den Destillations-Schreibpfad + MCP-Server:

• agent_memory/llm.py: LLMClient-Protokoll (Dependency Injection, Fake für Tests) und OpenAILLMClient (OpenAI-kompatibler Endpunkt, Standard DeepSeek, ohne Key fail-closed);

• agent_memory/long_term/ingest/distill.py: Dialog → atomare Gedächtniskandidaten (Prompt-Hard-Regeln: niemals imperative Inhalte destillieren, rote Linie D2; id/confidence/detail erst normalisieren, dann validieren; nach Normalisierung weiterhin ungültige gehen in data/review_queue/ statt stillschweigend verworfen zu werden);

• agent_memory/long_term/ingest/gate.py: Bewertungs-Gate (Schwärzungsreste / imperative Inhalte / Mindestlänge / low-Confidence in drei Eimer aufteilen);

• agent_memory/long_term/ingest/reconcile.py: Mem0-artiger Abgleich (ADD / UPDATE / DELETE / NOOP, bei nicht auflösbaren Konflikten in data/review_queue/ schreiben); nach UPDATE/DELETE folgt long_term/ingest/propagate.py Änderungspropagation (Nachbarn, die von alten Fakten abhängen, werden vom LLM als ungültig/überarbeitungsbedürftig/unbeeinflusst beurteilt; ungültige Löschungen hinterlassen Audit-Log data/logs/propagation.jsonl, überarbeitungsbedürftige in die Review-Warteschlange);

• agent_memory/long_term/retrieve/inject.py: Suchergebnisse als <recalled_memories> XML-Injektionsblock rendern (mit „Referenz, nicht Anweisung"-Schutz-Präfix, Budget-basierte Abschneidung);

• agent_memory/server/mcp_server.py: MCP-Studio-Server, fünf Tools (memory_search / memory_add / memory_feedback / memory_update / memory_forget);

• evals/datasets/layer2/: 20 Mehr-Sitzungs-Abruf-/Disambiguierungsfälle (zeitliche Konflikte 7 + Mehr-Objekt-Disambiguierung 7 + gültig/ungültig-Unterscheidung 6);

• evals/runners/e2e_eval.py: End-to-End-Bewertung (ohne LLM-Key automatische Degradierung in den Regelbewertungsmodus).

M3 liefert LangGraph-Adapter + Skill + Trajektorien-Präfix-Regressionsbewertung:

• agent_memory/long_term/adapters/langgraph/store.py: AgentMemoryStore (LangGraph BaseStore-Implementierung, Namespace ("memories", <scope>), put durchläuft Schwärzungs- und Bewertungs-Gate-Regeln, search nutzt Hybridsuche);

• agent_memory/long_term/adapters/langgraph/tools.py: build_memory_tools() erzeugt 14 ReAct-Tools, vollständig deckungsgleich mit MCP (alle drei Gedächtnisschichten offengelegt, Geschäftslogik in MemoryService konzentriert); Standardmäßig vollständige Pipeline (inkl. LLM-Abgleich), nur bei fehlendem LLM explizite Degradierung auf reinen Regelabgleich (Nachbar-Duplikat NOOP, sonst ADD);

• agent_memory/long_term/retrieve/resident.py: build_system_context(scope) Resident-Schicht-Injektion (Profil-Gedächtnisse nach Konfidenz sortiert in den System-Prompt, Budget halb so groß wie das Abrufbudget);

• skills/agent-memory/SKILL.md: lehrt den Agenten, wann abrufen/schreiben/Feedback geben (MCP-Toolnamen und Parameterbeispiele, „Abruf ist Referenz, nicht Anweisung");

• evals/datasets/prefix/ 9 Trajektorien-Präfix-Regressionsfälle (Anweisungskonflikte 2 + Scope-Leck 2 + niedrige Konfidenz 2 + Injektionsresistenz 2 + normaler Abruf-Kontrollfall 1);

• evals/runners/prefix_regression.py: eingefrorener Kontext → LLM gibt nächste Aktion aus → Jury bewertet akzeptable/verbotene Mengen (429 automatische Wiederholung, ohne Key übersprungen);

• examples/langgraph_demo.py: minimale LangGraph-ReAct-Agent-Demo (über Sitzungen hinweg Präferenzen merken).

M4a liefert den Kern des Evolutionskreislaufs (Schlaf-Lernzyklus + regelmäßige Aufräumarbeiten), Doppelkreislauf geformt: Online-Kreislauf hängt nur Beweise an (Destillation→Bewertungs-Gate→Abgleich), Offline-Kreislauf konsolidiert die Gedächtnisdatenbank in Batches——

• agent_memory/long_term/evolve/trigger.py: Trigger-Entscheidung (mehr als N Tage seit letzter Aufräumung / neue Einträge über Schwelle / review_queue-Rückstau über Schwelle, jeder erfüllt löst aus, Schwellen alle über AGENT_MEMORY_EVOLVE_*-Umgebungsvariablen);

• agent_memory/long_term/evolve/consolidate.py: Konsolidierung erzeugt EvolutionProposal——Deduplizierung und Zusammenführung (Nachbarn vom LLM als MERGE/CONFLICT/UNRELATED beurteilt, CONFLICT wird nicht zwangsweise konvergiert, sondern an Menschen übergeben), Offline-Überprüfung der ältesten Einträge (nutzt judge_propagation aus long_term/ingest/propagate.py), Vorschläge zur Herabstufung/Archivierung lange nicht abgerufener Einträge; Vorschläge werden nur in data/review_queue/evolution/<timestamp>/ geschrieben, niemals direkt die Gedächtnisschicht verändert;

• agent_memory/long_term/evolve/verify.py: Drei-Stufen-Verifikation (boundary-Vertragsprüfung / retention-Benchmark-Query top-5 diff / safety-Schutz sicherer Gedächtnisse), jede nicht bestandene Stufe führt zur Gesamtablehnung;

• agent_memory/long_term/evolve/apply.py: Snapshot vor Promotion (data/snapshots/<timestamp>/), Audit nach Anwendung (data/logs/evolution_audit.jsonl), rollback(snapshot_id) Rollback;

• agent_memory/long_term/evolve/cycle.py: Fünf-Schritte-Orchestrierung (Trigger → gezielt → konsolidieren → verifizieren → beschneiden);

• models.py: MemoryEntry erhält neues Feld retrieval_count (Hybrid-Suche-Treffer +1, Nachbarsuche im Schreibpfad zählt nicht).

M4b liefert layer3-Bewertungsset + Evolutionsmetriken + echte Abnahme:

• evals/datasets/layer3/: 12 Fälle mit versteckten Querverbindungen über Sitzungen (Programmierszenario-Adaption der dritten Schicht „proaktiver Dienst" im Buch: Fakten und Pläne in verschiedenen Sitzungen, richtige Antwort erfordert proaktiven Hinweis auf den versteckten Konflikt; jeder Fall enthält Profil-Resident-Schicht-Gedächtnis

  • Abrufschicht-Detailgedächtnis, rubric.essential muss „proaktiver Hinweis auf versteckte Verbindung" enthalten);

• evals/runners/metrics.py: gepaarte Statistik (McNemar-Exakttest + gepaartes Bootstrap-Gewinnintervall, reine Funktionen ohne scipy-Abhängigkeit, bei Stichproben < 20 explizit „nicht ausreichend für starke Schlussfolgerungen" markiert);

• evals/runners/e2e_eval.py neu --baseline: dieselben Fälle paarweise mit leerer Datenbank erneut ausführen, Ausgabe von Sieg/Niederlage pro Frage, p-Wert, Holdout-Gewinnintervall; und drei Evolutionsmetriken erfassen——Aktivierungsrate (Anteil geschriebener Gedächtnisse, die abgerufen werden), Befolgungsrate (Anteil der Fälle, in denen die Jury bestätigt, dass die Entscheidungsgrundlage aus abgerufenen Gedächtnissen stammt), Holdout-Gewinn (mit Gedächtnis - Baseline-Punktedifferenz);

• echte Abnahme-Zahlen: layer3 mit Gedächtnis 91,67% vs. Baseline 0% (McNemar p=0,0010, n=12 nur Richtungsreferenz); Regression layer1 100% / layer2 100% / prefix 88,89%; evolve-Kreislauf echte Demo (inkl. einer boundary Ablehnung und einer merge-Promotion + Rollback) deckte zwei consolidate-Defekte auf, siehe AGENTS.md offene Probleme.

M5 liefert manuelle Überprüfungs-Interaktionsknoten + erzwungenen Update-Hook:

• config.py neu review_gate (off / ask / strict, Standard ask: Verhalten von memory_search bei Rückstau in der Review-Warteschlange) und review_turn_interval (Standard 3, Rundenintervall des Hooks), Umgebungsvariablen AGENT_MEMORY_REVIEW_GATE / AGENT_MEMORY_REVIEW_TURN_INTERVAL überschreiben;

• MCP-Tools von fünf auf sieben erweitert——neu memory_review_list (Details offener Aufgaben) und memory_review_resolve (approve unverändert speichern / modify Text ändern, Schwärzung + Bewertungs-Gate durchlaufen, dann speichern / discard verwerfen); memory_search erhält Review-Gate (ask-Stufe blockiert bis Benutzerbestätigung, strict-Stufe verweigert Lesen immer, off blockiert nicht); memory_add gibt pending_review-Details zur Überprüfung zurück;

• Destillations-Prompt neue harte Regel „Benutzerbestätigungs-Berechtigung": Vorschläge/Pläne/Schlussfolgerungen, die nur vom Assistenten einseitig vorgeschlagen und nicht vom Benutzer ausdrücklich bestätigt wurden, werden nicht gespeichert;

• scripts/memory_turn_hook.py: kimi-code Stop-Hook, zählt Runden pro Sitzung, unterbricht alle N Runden das Sitzungsende und injiziert Destillationsanweisungen (Material = Benutzernachrichten jeder Runde + unmittelbar folgende Assistant-Antworten), registriert in der benutzerweiten ~/.kimi-code/config.toml.

M6 liefert HTTP-Daemon + Scope-Disziplin:

• agent_memory/server/http_server.py: streamable-http-Daemon, bindet standardmäßig nur 127.0.0.1:8765 (Loopback-Adresse benötigt naturgemäß keine Authentifizierung), zusätzlich zu den MCP-Endpunkten zwei statische Routen /SKILL.md (vollständige Verteilung der Prompt-Schicht) und /bootstrap (Bootstrap-Anweisungen für neue Agenten); ein einzelner Bootstrap-Befehl genügt für die Anbindung, kein Dateikopieren mehr nötig;

• Scope-Disziplin (gemeinsame Bibliothek, mehrere Agenten/Projekte gemischt): SKILL.md neue Scope-Auswahlregeln (Gemeinsames in global, Projektspezifisches in repo:, bei Unsicherheit zuerst Benutzer fragen), memory_add fällt bei fehlendem Scope auf global zurück, gibt aber scope_reminder-Hinweis zurück;

• Windows-Daemon-Betrieb: scripts/start_http_server.cmd Start-Wrapper-Skript (automatischer Neustart bei Absturz bis zu 3 Mal, nach 3 Fehlversuchen data/state/http_server_FAILED.txt Fehlermarker für Menschen, Logs in data/logs/http_server.log)

  • Login-ausgelöster geplanter Task (Registrierungsskript scripts/register_task_s4u.ps1, benötigt Administratorrechte).

M7 liefert drei Gedächtnisschichten (langfristig / Arbeitsgedächtnis / kurzfristig) + einheitliche Schnittstelle:

• Paketstruktur-Migration: die fünf Unterpakete store/ retrieve/ ingest/ evolve/ adapters/ werden vollständig in agent_memory/long_term/ verschoben (logisch null Änderungen), neu working/ und short_term/;

• agent_memory/working/: Arbeitsgedächtnis (Operationsebene, aktueller Aufgabenstatus——Ziele/offene Punkte/Entscheidungen/Variablen/Notizen, ein Exemplar pro Scope, gespeichert in data/working/). Schreiben ist vollständiges Ersetzen, nur Schwärzung, kein Bewertungs-Gate; turn_watermark-Wasserstand zusammen mit stale_wm bestimmt, ob der Status veraltet ist;

• agent_memory/short_term/: Kurzzeitgedächtnis-Transkript-Adapter, parst native Agenten-Logs (z. B. wire.jsonl von kimi-code) in saubere Rundenfolgen, erstellt keine neuen Dateien;

• MCP-Tools von sieben auf dreizehn erweitert: neu memory_wm_read / memory_wm_write / memory_wm_clear (Arbeitsgedächtnis lesen/schreiben/löschen), memory_context (Resident-Profil + Arbeitsgedächtnis + Abruf in einem zusammensetzen), memory_transcript_read (Rundenlesen, since_turn inkrementell), memory_session_end (Sitzungsabschluss: Archivierung data/raw + gemeinsame Destillation + Aufräumen abgeschlossener offener Punkte, offene Punkte mit Veto).

Related MCP server: mnemo

Verzeichnisstruktur

agent-memory/
├── agent_memory/     # Python 包（扁平布局，import 名 agent_memory）
│   ├── config.py         # 配置（AGENT_MEMORY_* 环境变量覆盖）
│   ├── models.py         # 记忆条目 schema（M0 核心）
│   ├── long_term/        # 长期记忆：store / ingest / retrieve / evolve / adapters（M1-M4，M7 迁入）
│   ├── working/          # 工作记忆：当前任务状态，操作层（M7a）
│   ├── short_term/       # 短期记忆：transcript 适配层（M7b）
│   └── server/           # MCP server：stdio（M2）+ HTTP 常驻（M6）
├── skills/agent-memory/  # Skill 接入方式（M3）
├── scripts/              # 运维脚本：turn hook（M5）、HTTP 服务启动/计划任务注册（M6）
├── evals/                # 评估集：datasets / rubrics / runners（agent 禁改，D6）
├── tests/
└── data/                 # 运行时数据（gitignored）：raw / memory / working / review_queue / snapshots / state / logs

Schnellstart

uv sync          # 创建虚拟环境并安装依赖
uv run pytest    # 跑测试
uv run ruff check .

M2-Verwendung

LLM konfigurieren (für Destillation / Abgleich / LLM-Jury)

Der Destillations-Schreibpfad benötigt einen OpenAI-kompatiblen Endpunkt, Standard DeepSeek (https://api.deepseek.com, Modell deepseek-chat):

export AGENT_MEMORY_LLM_API_KEY=sk-...
# 可选覆盖：AGENT_MEMORY_LLM_BASE_URL / AGENT_MEMORY_LLM_MODEL
# 评估评委可单独配置（异源互审）：AGENT_MEMORY_JUDGE_LLM_API_KEY 等

Ohne konfigurierten Key funktionieren Abruf, manuelles Schreiben, Feedback, Löschen usw. (nicht LLM-abhängig) weiterhin normal; nur der Dialog-Destillationspfad meldet beim Aufruf einen Fehler (fail-closed).

CLI-Destillationsbefehl

Einen Dialog (JSON-Datei mit [{role, content}, ...]) durch die vollständige Schreibpipeline in die Datenbank aufnehmen:

uv run agent-memory distill --file conversation.json --scope repo:my-project \
    --source kimi-code --session-id 2026-08-19-session
# 管线：蒸馏 → 评价门 → 对账；无法自动收敛的冲突会写入 data/review_queue/

MCP-Server

Start: uv run python -m agent_memory.server.mcp_server (stdio).

MCP-Konfigurationsausschnitt für Claude Code / Kimi Code:

{
  "mcpServers": {
    "agent-memory": {
      "command": "uv",
      "args": ["run", "python", "-m", "agent_memory.server.mcp_server"],
      "env": {
        "AGENT_MEMORY_DATA_DIR": "C:/Users/<you>/.agent-memory/data",
        "AGENT_MEMORY_LLM_API_KEY": "sk-...",
        "AGENT_MEMORY_LLM_BASE_URL": "https://api.deepseek.com",
        "AGENT_MEMORY_LLM_MODEL": "deepseek-chat"
      }
    }
  }
}

Fünf Tools zum Start (ab M5 auf sieben erweitert, ab M7 auf dreizehn, siehe unten M5 / M7-Verwendung): memory_search (Hybridsuche + XML-Injektionsblock, Scope-Filter serverseitig erzwungen), memory_add (Dialog-JSON durch Destillationspipeline / einzelner content durch Schwärzung + Abgleich), memory_feedback (Konfidenz erhöhen/senken, bei Senkung unter low in Review-Warteschlange), memory_update (nach Schwärzung + Bewertungs-Gate aktualisieren), memory_forget (löschen).

End-to-End-Bewertung

uv run python evals/runners/e2e_eval.py --layers 1,2            # 无 key 时自动规则降级模式
uv run python evals/runners/e2e_eval.py --layers 1,2 --llm-judge # 真实 LLM 评委按 rubric 判定
uv run python evals/runners/e2e_eval.py --layers 3 --llm-judge --jobs 8   # layer3 跨会话隐藏关联
uv run python evals/runners/e2e_eval.py --layers 3 --llm-judge --jobs 8 --baseline
    # --baseline：同一批用例在空库下配对重跑，输出逐题胜负 / McNemar p 值 /
    # 配对 bootstrap 留出增益区间，以及激活率 / 遵循率 / 留出增益三个进化指标
uv run python evals/runners/e2e_eval.py --layers 2 --llm-judge --jobs 8   # 调高用例并发
uv run python evals/runners/e2e_eval.py --layers 2 --llm-judge --no-cache # 禁用响应缓存

Beschleunigungsmechanismen (im echten Modus standardmäßig aktiv):

• LLM-Antwort-Disk-Cache: jede Antwort von Destillation / Abgleich / Jury wird nach sha256(model + system + user) in data/logs/llm_cache/ zwischengespeichert (bereits gitignored). Bei erneutem Lauf treffen unveränderte Teile direkt den Cache, in Sekunden fertig; Modellwechsel führt automatisch zu Cache-Miss. --no-cache deaktiviert.

• Fall-Parallelität: --jobs N (Standard 4) führt Fälle mit Thread-Pool parallel aus, jeder Fall in eigenem temporärem Verzeichnis, 429-Ratenlimit mit automatischem exponentiellem Backoff und Wiederholung.

• Modell laden: bge-m3 wird pro Prozess einmal geladen (ca. 1-2 Minuten). Beim Ausführen mehrerer Layer --layers 1,2 verwenden, um alles in einem Lauf zu erledigen, nicht zwei Prozesse für je einen Layer starten.

Der Regel-Degradierungsmodus repräsentiert nicht die echte Destillationsqualität; für die formale Abnahme muss mit echtem LLM erneut ausgeführt werden.

M3-Verwendung

LangGraph-Anbindung

Ein selbstgeschriebener LangGraph-Agent hat drei Anbindungsmöglichkeiten, kombinierbar:

from agent_memory.long_term.adapters.langgraph.store import AgentMemoryStore
from agent_memory.long_term.adapters.langgraph.tools import build_memory_tools
from agent_memory.long_term.retrieve.resident import build_system_context
from langgraph.prebuilt import create_react_agent

# 1) BaseStore：namespace 约定 ("memories", <scope>)，put/search/delete 直接映射到记忆内核
store = AgentMemoryStore()          # 配置走 AGENT_MEMORY_* 环境变量
store.put(("memories", "repo:myproj"), "db-choice",
          {"content": "本项目数据库定为 SQLite，文件 data/app.db。", "confidence": "high"})

# 2) ReAct tool：recall_memories / save_memory 挂进 tools 列表
tools = build_memory_tools()

# 3) 常驻层：profile 类记忆渲染进 system prompt（预算是召回预算的一半）
prompt = "你是用户的编程助手……\n\n" + build_system_context("repo:myproj")

agent = create_react_agent(model, tools, prompt=prompt, store=store)

Vollständig lauffähiges Beispiel siehe examples/langgraph_demo.py (uv run python examples/langgraph_demo.py, benötigt AGENT_MEMORY_LLM_API_KEY).

Beachten: BaseStore.put ist eine Low-Level-Synchron-Schnittstelle: Der Aufrufer muss destillierte atomare Inhalte liefern, die Adapterschicht durchläuft Schwärzungs- und Bewertungs-Gate-Regeln (imperative Inhalte werfen direkt Fehler), aber keine LLM-Destillation; der Abgleich des save_memory-Tools ist ein LLM-freier reiner Regelpfad (Nachbar-Duplikat NOOP, sonst ADD), Konfliktkonvergenz läuft weiterhin über die M2-Destillationspipeline.

Skill-Anbindung

skills/agent-memory/SKILL.md ist die Prompt-Schicht, die eingebetteten Agenten (Kimi Code / Claude Code) lehrt, wann abrufen, schreiben, Feedback geben. Installation (zusammen mit MCP-Server verwenden):

• Kimi Code: skills/agent-memory/ nach ~/.kimi-code/skills/agent-memory/ kopieren oder symbolisch verlinken;

• Claude Code: nach ~/.claude/skills/agent-memory/ kopieren;

• Gleichzeitig den agent-memory-Server gemäß obiger MCP-Konfiguration anhängen, damit die Toolnamen im Skill (memory_search usw.) eine Implementierung haben.

Trajektorien-Präfix-Regressionsbewertung

Eingefrorener Kontext (system + bereits injizierter Gedächtnisblock + neueste Benutzernachricht) → LLM gibt nächste Aktion aus → Jury bewertet, ob sie in der akzeptablen Menge liegt und die verbotene Menge nicht berührt. Deckt vier Grenzszenarien ab (Anweisungskonflikt / Scope-Leck / niedrige Konfidenz / Injektionsresistenz) + normaler Abruf-Kontrollfall:

uv run python evals/runners/prefix_regression.py             # 需 LLM key，无 key 整体跳过
uv run python evals/runners/prefix_regression.py --seeds 3   # 多种子报均值与区间
uv run python evals/runners/prefix_regression.py --no-cache  # 禁用 LLM 响应缓存（默认开）

429-Ratenlimit wird automatisch mit Intervallen wiederholt; LLM-Antwort-Disk-Cache wird mit e2e_eval gemeinsam in data/logs/llm_cache/ genutzt. Diese Bewertung hat keinen Regel-Degradierungsmodus (das Actor-Verhalten ist selbst das Testobjekt).

M4-Verwendung

Schlaf-Lernzyklus (evolve)

# dry-run：只到提案为止，打印提案摘要，不验证、不应用
uv run agent-memory evolve --dry-run

# 完整循环：触发 → 整合 → 三档验证 → 通过则晋升（自动快照 + 审计）
uv run agent-memory evolve

# 只整理某个 scope
uv run agent-memory evolve --scope repo:my-repo

Trigger-Bedingungen (eine erfüllt, Schwellen mit AGENT_MEMORY_EVOLVE_*-Umgebungsvariablen überschreibbar): mehr als 7 Tage seit letzter Aufräumung (EVOLVE_INTERVAL_DAYS), mehr als 50 neue Einträge (EVOLVE_NEW_ENTRIES_THRESHOLD), Review-Warteschlange-Rückstau über 10 (EVOLVE_REVIEW_BACKLOG_THRESHOLD).

Die Aufräumarbeit erzeugt einen Vorschlag (data/review_queue/evolution/<timestamp>/proposal.yaml), keine direkte Umschreibung: Drei-Stufen-Verifikation (boundary / retention / safety) führt bei jeder nicht bestandenen Stufe zur Ablehnung, Vorschlag bleibt für Menschen archiviert; nur wenn alle bestanden, Promotion——vor Promotion Snapshot der Gedächtnisschicht (data/snapshots/<timestamp>/), nach Promotion Audit-Log (data/logs/evolution_audit.jsonl). Rollback mit agent_memory.long_term.evolve.apply.rollback(snapshot_id, settings, embedder) stellt die Gedächtnisschicht aus dem Snapshot wieder her und baut Indizes neu auf.

M5-Verwendung

Manuelle Überprüfung (zwei Interaktionsknoten der Review-Warteschlange)

Ungültige Destillationsausgaben, vom Bewertungs-Gate als niedrige Konfidenz eingestufte, nicht konvergierbare Abgleichkonflikte gehen alle in data/review_queue/ zur manuellen Entscheidung. Die Überprüfung erfolgt über zwei MCP-Tools:

• memory_review_list: listet offene Aufgaben-Details (Quelle, Grund, Inhalt);

• memory_review_resolve: Entscheidung——approve unverändert speichern / modify Text ändern, Schwärzung + Bewertungs-Gate durchlaufen, dann speichern / discard verwerfen. Nach erfolgreicher Entscheidung wird die Warteschlangendatei gelöscht; raw_record-ähnliche offene Aufgaben können nicht direkt gespeichert werden.

Review-Gate (AGENT_MEMORY_REVIEW_GATE, Standard ask): Verhalten von memory_search bei Rückstau in der Warteschlange—— ask gibt status=blocked zurück und wartet auf Benutzerbestätigung (acknowledge_pending=true gibt frei), strict verweigert Lesen immer (für unbeaufsichtigte Szenarien), off blockiert nicht. memory_add gibt pending_review-Details zurück, der Agent soll sie dem Benutzer einzeln melden und um Entscheidung bitten (SKILL.md hat den entsprechenden Ablauf).

Erzwungener Gedächtnis-Update-Hook

scripts/memory_turn_hook.py ist der Stop-Hook von kimi-code: zählt Runden pro Sitzung, unterbricht alle AGENT_MEMORY_REVIEW_TURN_INTERVAL (Standard 3) Runden einmal das Sitzungsende, injiziert Destillationsanweisungen (Material = Benutzernachrichten jeder Runde + unmittelbar folgende Assistant-Antworten). Bereits registriert in der benutzerweiten ~/.kimi-code/config.toml, wirkt für alle Projektsitzungen; andere Hosts können das Skript als Referenz selbst anhängen.

M6-Verwendung

HTTP-Daemon

Im stdio-Modus startet der Host den Server als Unterprozess, der mit der Sitzung lebt und stirbt; im HTTP-Modus ist es ein langlaufender lokaler Dienst, jeder Agent-Host, der HTTP-Anfragen senden kann, registriert eine URL und erhält alle dreizehn Tools:

uv run python -m agent_memory.server.http_server
# 默认监听 http://127.0.0.1:8765/mcp（只绑回环地址，天然免鉴权）
# 覆盖：AGENT_MEMORY_HTTP_HOST / AGENT_MEMORY_HTTP_PORT

Der Dienst hat zwei weitere statische Routen: /SKILL.md (vollständiger Text der Prompt-Schicht) und /bootstrap (Bootstrap-Anweisungen). Ein neuer Agent muss nur den Inhalt von /bootstrap erhalten: http://127.0.0.1:8765/mcp registrieren (Transporttyp streamable-http) + /SKILL.md lesen und befolgen, keine Dateien kopieren.

Windows-Daemon (geplanter Task)

scripts/start_http_server.cmd ist das Start-Wrapper-Skript: bei abnormalem Beenden 60 Sekunden warten, dann neu starten, maximal 3 Mal; nach 3 Fehlversuchen data/state/http_server_FAILED.txt Fehlermarker für Menschen; Logs in data/logs/http_server.log. scripts/register_task_s4u.ps1 registriert einen Login-ausgelösten geplanten Task (S4U-Hintergrundmodus, völlig fensterlos), benötigt Administratorrechte. Beide Skripte müssen reines ASCII bleiben (cmd.exe liest .cmd als GBK, PowerShell 5.1 liest BOM-lose .ps1 als ANSI, nicht-ASCII beschädigt die Analyse).

M7-Verwendung

Einheitliche Kontextzusammenstellung und Arbeitsgedächtnis

memory_context(scope, query?, k?, current_turn?) setzt in einem Aufruf drei Abschnitte zusammen: Resident-Profilblock (Profile im Langzeitgedächtnis) → Arbeitsgedächtnisblock (aktueller Aufgabenstatus) → Abrufblock (nur mit query wird das Langzeitgedächtnis durchsucht). Für die tägliche Pflege des aktuellen Aufgabenstatus gibt es drei Arbeitsgedächtnis-Tools:

• memory_wm_write(scope, goal?, decisions?, variables?, todos?, notes?, turn_watermark?): vollständiges Ersetzen (kein Zusammenführen, nicht übergebene Felder werden geleert), nur Schwärzung, kein Bewertungs-Gate;

• memory_wm_read(scope, current_turn?): Lesen + Frische-Bewertung (stale_wm=true bedeutet, die aktuelle Rundenanzahl hat den turn_watermark-Wasserstand des Arbeitsgedächtnisses überschritten——„bis zu welcher Runde dieser Status aktualisiert wurde", Status könnte veraltet sein);

• memory_wm_clear(scope): leeren (idempotent, wenn nicht vorhanden kein Fehler).

Das Arbeitsgedächtnis ist ein Entwurf auf Operationsebene: Schlussfolgerungen abgeschlossener Punkte müssen in das Langzeitgedächtnis destilliert werden (memory_add oder memory_session_end unten), erst dann sind sie gespeichert.

Sitzungslog lesen und Sitzungsabschluss

memory_transcript_read(log_path, adapter?, since_turn?) parst Agent-Sitzungslogs (z. B. wire.jsonl von kimi-code, Format automatisch anhand des Dateinamens erkannt) in saubere Rundenfolgen (user/assistant/tool); since_turn in Kombination mit dem Arbeitsgedächtnis-Wasserstand für inkrementelles Lesen (nur Runden nach dem Wasserstand zurückgeben).

memory_session_end(scope, conversation_json?|log_path?, ...) ist der Standard-Abschluss einer Sitzung, in einem Schritt: Originaltext archivieren (data/raw/, nur anhängen, nicht umschreiben) → gemeinsame Destillation (Dialog + Arbeitsgedächtnis-Snapshot als Referenzkontext) → abgeschlossene offene Punkte im Arbeitsgedächtnis aufräumen. Wenn noch offene Punkte im Arbeitsgedächtnis vorhanden sind, wird ein Veto ausgelöst (Archivierung/Destillation/Aufräumen werden nicht ausgeführt), bei bestätigtem Ende force=true übergeben. Es ist eine zweigleisige Arbeitsteilung mit dem rollierenden Destillations-Hook alle N Runden: Der Hook sichert gegen Absturzverlust in der Mitte ab, session_end macht den Standard-Abschluss.

Drei architektonische rote Linien

Details siehe AGENTS.md. Kurz gesagt: Daten in drei Schichten getrennt (raw nur anhängen, memory ist die einzige Quelle der Wahrheit, index kann neu aufgebaut werden, niemals manuell ändern); Schreiben muss die Tore Schwärzung→Destillation→Abgleich durchlaufen; evals / rubric / Veröffentlichungsschwelle / Audit-Logs dürfen nicht von Agenten selbst geändert werden.