AWHM Lite

Externes Langzeitgedächtnis für LLM-Agenten. Keine Cloud, keine API-Schlüssel, läuft vollständig lokal.

AWHM Lite verleiht jedem LLM über Gespräche hinweg ein persistentes Gedächtnis – durch Append-only-Logging, regexbasiertes Muster-Matching, einen widerspruchsbewussten Gedächtnisgraph, symbolische Konsolidierung (ohne ein einzigen LLM-Aufruf) und Abruf mittels lexikalischer + semantischer Merkmalsfusion.

Status: Forschungsprototyp. Entwickelt im Februar 2026, veröffentlicht im August 2026; v0.2.0 hat es gehärtet, v0.3.0 hat Hooks, Stufe 2, Entitätsauflösung, Zeitreise, SQLite-Speicherung und die Auswertung auf einem realen Korpus ergänzt. 145 Tests, CI auf Python 3.11 bis 3.13.

Projektdokumentation

• docs/awhm-whitepaper.md: das vollständige AWHM-Architekturpapier, von dem dieses Projekt eine Teilmenge ist

• docs/awhm-whitepaper-vs-lite.md: was Lite behält und was es weglässt

• docs/Future Plans.md: der geplante nächste Schritt (eine stille Middleware, die in jeder Gesprächsrunde unauffällig mitläuft)

Related MCP server: claude-memory-mcp

Wie das entstanden ist

Die Architektur und die Ideen dahinter stammen von mir. Der Code wurde vollständig von KI-Coding-Agenten (hauptsächlich Claude Code) unter meiner Leitung geschrieben: Ich habe das Design festgelegt, die Aufgaben abgegrenzt, die Ergebnisse geprüft und die Richtung vorgegeben. Das Whitepaper ist auf demselben Weg entstanden.

INTERACTION TIME                        OFFLINE (SESSION END)
────────────────────                    ─────────────────────
┌──────────────────┐   real-time log    ┌──────────────────────┐
│  PRIMARY AGENT   │──────────────────► │  STAGE 1 CONSOLIDATION│
│  (user-facing)   │   (middleware,     │  (symbolic only,      │
└──────┬───────────┘    no LLM)         │   zero LLM calls)     │
       │                                └──────────┬───────────┘
       │ queries                                   │ writes
       ▼                                           ▼
┌──────────────┐    ┌──────────┐    ┌──────────────────────┐
│  RETRIEVAL   │◄───│ SESSION  │    │    FLAT MEMORY GRAPH  │
│  ENGINE      │    │ BUFFER   │    │                      │
│              │◄───┤(checked  │    │  nodes: episodic,    │
│ BM25 +       │    │ first)   │    │  semantic, procedural│
│ embedding    │    └──────────┘    │                      │
│ similarity   │◄───────────────────│  edges: typed        │
│              │                    │  strength: rec + freq│
└──────────────┘                    └──────────────────────┘
       ▲
       │ fallback (first ~10 sessions)
┌──────┴───────┐
│   RAW LOGS   │
│ (append-only)│
└──────────────┘

Installation

# Core (numpy, spaCy, dateparser) plus the sentence-transformers embedding model
pip install -e ".[embeddings]"

# spaCy NER model (used in consolidation; without it, entity extraction is skipped)
python -m spacy download en_core_web_sm

# Claude Code MCP integration
pip install -e ".[mcp]"

# Optional: Anthropic SDK client for Stage 2 (the default Stage 2 client is
# the Claude Code CLI and needs nothing extra)
pip install -e ".[anthropic]"

sentence-transformers ist optional, weil es PyTorch nach sich zieht. Ohne diese Bibliothek Sessions einfach mit use_mock_embeddings=True starten (deterministische Hash-basierte Vektoren, völlig ausreichend für Tests und um die CLI auszuprobieren). Das echte Modell (all-MiniLM-L6-v2, 22 MB) wird bei der ersten Verwendung heruntergeladen.

Schnellstart

Python-API

from awhm import AWHMSession
from awhm.types import Role

# Start a session (also usable as a context manager: `with AWHMSession.start_session() as session:`)
session = AWHMSession.start_session()

# Log messages
session.log_message(Role.USER, "My name is Alice")
session.log_message(Role.ASSISTANT, "Hello Alice!")
session.log_message(Role.USER, "I prefer Python over JavaScript")
session.log_message(Role.USER, "The API endpoint is https://api.example.com/v2")

# Query memory (works immediately via session buffer)
results = session.query("What language does the user prefer?")
for r in results:
    print(f"[{r.source}] {r.content}")

# Consolidate into long-term memory graph
session.consolidate_current()

# End session (flushes WAL, saves graph)
session.end_session()

Integration mit einem LLM

AWHM sitzt als Middleware. Es selbst ruft kein LLM auf – Sie betten es in ein, was auch immer Sie verwenden:

from awhm import AWHMSession
from awhm.types import Role

session = AWHMSession.start_session()

def handle_message(user_text):
    session.log_message(Role.USER, user_text)

    # Retrieve relevant memories
    memories = session.query(user_text, k=5)
    memory_context = "\n".join(f"- {m.content}" for m in memories)

    # Inject into system prompt
    system = f"Memories from past conversations:\n{memory_context}"
    response = your_llm_call(system_prompt=system, user_message=user_text)

    session.log_message(Role.ASSISTANT, response)
    return response

# At end of conversation:
session.consolidate_current()
session.end_session()

CLI

awhm status                        # Show system stats
awhm query "Python preferences"    # Search memory
awhm query "API endpoint" --include-history --trace
awhm consolidate                   # Run Stage 1 on pending sessions
awhm snapshot create               # Backup current graph
awhm snapshot list                 # List snapshots
awhm snapshot restore --path FILE  # Restore from snapshot
awhm delete NODE_ID                # Hard-delete a node (privacy)
awhm eval --json                   # Run built-in benchmark report

Claude-Code-Integration (Hooks, empfohlen)

Mit Hooks funktioniert das Gedächtnis in jeder Runde, ohne dass das Modell ein Tool aufrufen müsse. Jeder Hook ist ein eigener kurzlebiger Prozess: der Session-Puffer wird zwischen den Hooks aus seinem Write-Ahead-Log wiederhergestellt.

awhm hook settings          # prints the block to merge into ~/.claude/settings.json

Hooks blockieren niemals eine Session: Jeder Fehler wird nach stderr geschrieben und der Prozess endet mit Exit-Code 0. Mit AWHM_DATA_DIR lässt sich festlegen, wo die Erinnerungen leben.

Claude-Code-Integration (MCP)

AWHM Lite wird auch als MCP-Server ausgeliefert, sodass Claude Code es als ein Tool verwenden kann.

Einrichten

# Install with MCP support
cd awhm-lite
pip install -e ".[mcp]"

# Register with Claude Code
claude mcp add --transport stdio awhm-lite -- awhm-mcp

Oder manuell in .claude/settings.json hinzufügen:

{
  "mcpServers": {
    "awhm-lite": {
      "type": "stdio",
      "command": "awhm-mcp",
      "env": {
        "AWHM_DATA_DIR": "~/.awhm"
      }
    }
  }
}

Verfügbare MCP-Tools

Sobald verbunden, hat Claude Code automatisch Zugriff auf diese Werkzeuge und kann Erinnerungen über Gespräche hinweg abfragen und ablegen.

So funktioniert es

Rohdaten des Protokolls

Jede Nachricht wird zu einer JSONL-Datei hinzugefügt (einer Avocado pro Session). Append-only, außer bei endgültigen Löschungen aus Datenschutzgründen nie verändert Änderungen. Das ist die Erdung der Wahrheit.

Session-Puffer

Ein regex-basiertes Muster verwendet wird in Echtzeit auf jede Benutzernachricht und identifiziert folgende Muster:

• Korrekturen: „Also eigentlich ist X doch das Y“, „nein, es ist X“

• Präferenzen: „Ich bevorzuge X“, „immer X nehmen“, „nie X“

• Tierarten: „der Endpunkt ist X“, „Ich heiße X“

• Ergebnisse:: „das hat funktioniert“, „das ist fehlgeschlagen“

Es fängt ca. 60–70 % des expliziten Signals ab – und das ohne LLM-Aufruf. Der Puffer wird beim Abruf zuerst geprüft und liefert so eine Sofortkontinuität innerhalb der Session. Beim normalen Abruf werden diejenigen Puffer-Einträge verborgen, die eine spätere Aussage überholt (gleicher Slot oder eine explizite Korrektur ein paar Nachrichten später). Korrekturen gewinnen also. Persistiert wird per Write-Ahead-Prot per Session (Flush-Intervall 30 Sekunden, wenn sich nichts geändert hat).

Memory-Graph

Ein flacher gerichteter Graph mit drei Knotenarten (episodisch, semantisch, prozedural) und drei Kantenarten (temporal, Abstraktion, Assoziation).

Jeder Knoten hat zusätzlich Metadaten zum Widerspruchslebenszyklus:

• kanonischer_schlüssel (eine identity à la Slot, z.B. fact:meine bevorzugte Sprache)

• Status (active, superseded, retracted – also aktiv, ersetzt, zurückgezogen)

• supersedes (ältere Knoten-IDs, die von dem Knoten

• valid_from / valid_to (gültig ab / gültig bis)

• Konfidenz

Gespeichert als JSON, in den Speicher geladen.

Abwärtskompatibilität: Ältere Tweet-Dateien (die weitere Felder enthalten) werden beim Start automatisch migriert.

Stärke-Scoring (Likely)

Jeder Knoten hat einem zusammengesetzten Stärke-Rating (strength):

S(v) = 0.4 * recency + 0.6 * frequency

Aktualität nutzt Rekurrenz: s_rec = (1 + 0.1 * hours)^(-0.3) – also grob 0.71 nach 24 Stunden, 0.40 nach 7 Ihr 0.27 nach 30 Tagen days. Die Häufigkeit ist die Zugriffswertellung gegen das 90. Perzentil.

Konsolidierung (Stufe 1)

Am Ende einer Session ablaufen, null LLM-Aufrufe:

1. NER durchgeführt suis spaCy: Personen, Organisationen, Orte, Produkte. Heißt manuell mit CARDINAL (Zahlen), MONEY (Geldbeträge), DATE (Datumsangaben) ... und Ähnlichem – die hat zuvor nur Rauschen erzeugt. Dies konfigurierbar über ner_labels.

2. Zeitliche Parser (Temporal parsing) via ", Resolve gesternoder5. März` in ISO-Zeitstempel

3. Regelbasierte Extraktion: dieselben Regex-Muster wie beim bloßen Session-Puffer, über die neuen Nachrichten

4. Entity Linking: Entitäten werden mit vorhandenen Knoten abgeglichen (ein Kosinus-Matrixmultiplikation plus Der Ganze + Verkettungs-Typ muss stimmen ÜberStringbasierte Sicherheitsprüfung)

5. Deduplizierung: identische Aussagen innerhalb eines Batches werden zusammengefasst; – Duplikate (Kosinus-Schwelle größer > 0.92) stärken den bestehenden Knoten, statt neue zu erschaffen.

6. Commit: Kanonische-Kennt gemacht, widersprechende frühere Erinnerungen werden ersetzt, Kanten und Knoten, Stärke-stronghold.

Widersprüche: Die kanonischen Notierungen

Ein kanonischer Schlüssel canonical_key bestimmt den Slot, den gelesene Aussage ausfüllt. Zwei aktive Erinnerungen, den gleichen Slot beanspruchen, widersprechen sich. Die neuere ersetzt dann die ältere (status=superseded, valid_to gesetzt, supersedes-Verknüpfung von dem neuen Knoten).

Die Zugänge, bewusst konservativ weil kein LLM ur Intention:

• Gleicher Schlüssel: führt immer – der Slot wird mit dem neuen bevorzugten Wert belegt.

• Gleiche Familie (Sprache-Beleidigungen): „Präferenz-/Politik“-Familie : Nur eine explizierte Korrektur (z.B. „Ich bevorzuge eigentlich Rust“,) über die vorherige Aussage derselben Familie schreiben, sofernn dies in correction_window_messages (Default 3, d.h. innerhalb der nächsten drei Nachrichten Nachfahren) dieser Session geschieht. Ohne solche Korrekturmarker bleiben Präferenzen additiv: „Tabs sind okay“ und „Dark“ Mode bitte – beide erhalten Sichtbarkeit zugleich.

• Faktenfamilie– gehört: Hier überschwemmt nur ein Multiple je Schlüssel (exactMatch). Eine Korrektur an einem API-Endpunkt überschreibt also nie und nicht den Namen.

• Etwas anderes zunächst kein Slider zu – es wird kein Key, also neue / validücke Ergänzung.

Entitys (benannte Objekte)

Benannte Unterteilungen werden immer zu einem Knoten aufgelöst, egal wie sie geschrieben sind. Oberflächen treten normalisiert (case, Possessiv-Endungen und gezielte Firmenzusatz-Schreibweisen, Domains: z.B. "Acme Holdings Limited" und "acme.com" -> zu-normalisierten „acme" ), werden verglichen (exact alias, eindeutige Wichtungsfamilie–ault; also wenn "Acme" im Namen k. "Acme Holdings"), und zuletzt über eine disambiguierung durch Einbettungshingesehen entsprechen same Entity type sind Type. Jede Entgegenahme wird als zusätz loader, und jede Aussage erhält Be-attention edges zu den genanntenTopic – so wandert das Retrieval von „ece“ zu allem, was über besagte Entität weiß.

Stufe 2 (optional LLM-Refinement / ohne api-Keys)

Stufe 1 ist eine strikte Begrenzung: Sie fängt ab „Ich bevorzuge Rust“, aber sie sieht weiter, wenn klein durch „machen wir eben Rust,“ mL: also “Stufe 2” – das Angebot eines LLM (offline), das retro&sich die Erinnerungen vorschlägt, die die Regeln gefunden haben. LLM: nur dabei … Jeder Vorschlag wird in der Engine validiert(Format, zitiert, Nachrichtensexistieren?, hebt. Untergrenze`), aussortiert werdeniss das grep ohne Erinnerung– und Präzedenz-Was: ganz durch “V”-Die Retrie-Funktion bleibt die of ours.

Das default client – ruft die Claude-Code-Befehlszeile auf (claude -p mit strukturierter Ausgabe) – nutzt also Ihr bestehendes Login und speichert logically kein key eine Stelle. Die Ausführung als signal do, sodass Memory-Hooks innerhalb nicht zusätzlaufen.

awhm consolidate --stage2                    # Claude Code CLI, default model
awhm consolidate --stage2 --stage2-model sonnet

from awhm import AWHMSession, AWHMConfig

config = AWHMConfig(stage2_enabled=True, stage2_model="sonnet")
with AWHMSession.start_session(config) as session:   # builds ClaudeCodeClient
    ...
    session.consolidate_current()

Jedes Objekt mit einer complete_json(system, user, schema) -> str als Client funktioniert (llm_client=...). Eine zusätzliche Client für Anthropic-SDK ist ebenso enthalten für alle, die API-Rechnung bevorzugen (stage2_client="anthropic", extra Zusatz [anthropic]).

Suche (Retrieval)

Kein LLM-Awake. Feature-basierte Fusion:

1. Puffer-Check: Zuerst in den Puffer ť; Suchtreffer treffen ( instand, über Rank-Graph).

2. Variantenfestlegung: BM25-Summenüber und sowie-Similarity (Vereinigung). We are located BM25-Index im Prozess auf (Lucene-style IDF, damit auch kleine Korpora sinnvoll providen) – Chelt cached bis sich Knoten/Ebenen ändern.

3. Verlaufsfilter: Standardfalls dürfen nur aktive Graphen (graph nodes mit status=active) verwendet.

4. Merkmalsscore : Semantische Ähnlichkeit; wiederholung lexikalischer Score – plus hardness Konstellation– zuzüglich confidence minus einer Widerspruchs-Strafe. Würde Strength neu berechnet – nur unter den Kundenpräsent eingegrenzt sind.

5. Returniert top-k (Default: 10)

6. Nachwechseln (Aktion) : I’m one.-Hob-Nachbarn der Kandidaten (linked entity, subsequent episodes) tak, hinzu andduction with verbessertem weightweight Active. Nur Anchor die aktuell sind réal.).

7. Cold-Start-Fallback: Ersten ~10 Sessions bis BM25 zusätzlich zusätzlich über rohe Protokolle. Diese werden asse in [0, raw_log_score_scale] eingeschleust, So no neues Graph-Spiel übertrifft.

Zeitreise

Fakten enthalten a Gültigkeitsfenster. Datumformulierungen: „seit"/“von“ setzen valid_from und „bis“ setzen valid_to; eine Verknüpfung ersetzt das Fenster ältere L. query(..., as_of="2026-03-01") beantwortet, was in diesem Zustand zu diesem Zeit gel.. Zeitpunkt – include incl. mit veralteten und ersetztemte Entfernungen; siehe unten:

awhm query "API endpoint"                       # what is true now
awhm query "API endpoint" --as-of 2026-02-01    # what was true then

Setzen Sie include_history=True, um ersetzte / zurückgezogene Erinnerungen zu zeigen.

Verwenden Sie mit with_trace=True zu pro Ergebnis – derRanking momentsome details jede Treffer.

Auswertung / Evaluierung

Die integrierte Benchmark ist eine liste synthetische-(Smoke)-Test: drei Anfragetypen mit vielen Vernichtigungen plus eine Löschskontrolle. Echte Zahlen kommen aus dem Abspielen eines Körpers –>:

awhm eval                                            # built-in synthetic benchmark
awhm eval --corpus my_sessions.json                  # native format, see below
awhm eval --corpus longmemeval_s.json --longmemeval --limit 50

Beide melden Recall@k, nDCG@k, Widerspruchsfehlerrate, p50/p95-Latenz sowie kategorieweises Recall. Das native Korpusformat ist {"sessions": [{"id", "messages": [{"role", "content"}]}], "questions": [{"id", "question", "expected": [...], "forbidden": [...], "as_of", "category"}]}. LongMemEval-Instanzen werden konsolidiert und einzeln abgefragt, dem Benchmark-Protokoll folgend. Der Abgleich erfolgt über Antwort-Teilstrings, eine bewusste untere Schranke: Paraphrasierte Treffer werden nicht gezählt.

Gemessen (nur Stage 1, Oracle-Split, 500 Fragen): Recall@5 0.196, von 0.40 bei Single-Session-Nutzerfakten bis 0.00 bei Präferenzen, bei 4 ms pro Anfrage. Das ist die sichtbare Grenze des Regex-Ansatzes; Stage 2 existiert, um sie anzuheben. Vollständige Tabelle, Einschränkungen und Reproduktion in docs/benchmarks.md.

Konfiguration

Alle Parameter sind über AWHMConfig konfigurierbar:

from awhm.config import AWHMConfig

config = AWHMConfig(
    data_dir="~/.my-project-memory",
    k=20,
    w_rec=0.5,
    w_freq=0.5,
)

Datenverzeichnis

~/.awhm/
├── logs/                          # Raw JSONL logs (one per session)
│   ├── {session_id}.jsonl
│   └── ...
├── graph/
│   ├── memory_graph.json          # The memory graph (storage_backend="json")
│   └── memory_graph.sqlite        # ... or one row per node (storage_backend="sqlite")
├── snapshots/
│   └── snapshot_{timestamp}.json  # Manual backups
├── wal/
│   └── {session_id}.wal           # Per-session write-ahead logs
└── meta/
    ├── consolidated_sessions.json # Tracks which sessions have been processed
    ├── deletion_tombstones.jsonl  # Deletion tombstones
    └── deletion_ledger.jsonl      # Deletion audit ledger

Tests

pip install -e ".[dev]"
pytest tests/ -v

Alle Tests verwenden MockEmbeddingService (deterministisch über Prozesse hinweg, ohne Modelldownload). ruff check . führt den Linter aus; CI führt beides unter Python 3.11, 3.12 und 3.13 aus.

Abhängigkeiten

BM25 ist im Paket selbst implementiert (etwa 60 Zeilen), eine Rangfolge-Abhängigkeit besteht ebenfalls nicht.

Das Einbettungsmodell (all-MiniLM-L6-v2, 22 MB) wird bei der ersten Verwendung nach ~/.cache/huggingface heruntergeladen.

Projektstruktur

src/awhm/
├── __init__.py            # AWHMSession facade (top-level API)
├── config.py              # All parameters + path helpers
├── types.py               # Enums: Role, NodeType, NodeStatus, EdgeType, BufferEntryType
├── mcp_server.py          # MCP server for Claude Code
├── hooks.py               # Claude Code hook commands (prompt / stop / session-end)
├── timeutil.py            # Timestamp parsing, validity windows
├── eval/                  # Built-in benchmark + real-corpus replay (LongMemEval loader)
├── raw_log/               # Append-only JSONL logging
├── session_buffer/        # Regex pattern matching + WAL
├── graph/                 # Memory graph, strength scoring, JSON/SQLite stores
├── consolidation/         # NER, temporal, extraction, entities, dedup, Stage 2, pipeline
├── retrieval/             # Embedding, BM25, ranking, retrieval engine
├── snapshots/             # Snapshot create/restore/list
├── deletion/              # Hard-delete cascade
└── cli/                   # argparse CLI