ENGRAM — Neural Memory Engine for Qwen Agents

Track 1 · MemoryAgent — persistent memory that recalls, revises, consolidates, blocks unsafe actions, and explains every decision under a fixed token budget.

Comment

Track 1 · MemoryAgent — running on Alibaba Cloud ECS, all inference on Qwen Cloud (qwen3.7-plus / qwen3.6-flash / text-embedding-v4).

RAG retrieves documents. ENGRAM governs an agent's evolving beliefs and actions.

ENGRAM is a verifiable memory control plane for Qwen agents. It fixes the three memory failures every production agent hits: amnesia across sessions, stale contradictions in vector stores, and unbounded full-history context stuffing. The engine combines Qwen-powered extraction, LLM-arbitrated belief revision, hybrid scored retrieval with a safety-critical rescue floor, and sleep-cycle consolidation — and every recall is explainable in the live memory constellation. Every claim below is backed by a reproducible benchmark and ablation suite.

Why it matters — the same engine, personal and vertical

One memory substrate supports personal assistants, customer-support agents, DevOps copilots, and sales/CRM agents. Two live scenarios prove it:

  • Personal (https://engram.hackthon.site): diet + allergy recalled across sessions; a job change supersedes the old employer fact instead of contradicting it.
  • DevOps runbook memory (https://engram.hackthon.site/?seed=devops): critical operational prohibitions ("never restart billing pods directly — drain at the gateway first"), incident post-mortems, infrastructure facts, and a superseded GPU-driver assumption survive across sessions and surface exactly when the agent needs to act safely. Fragmented ALB-migration notes consolidate into one durable fact during the sleep cycle.

Measured results - 5/5 scenarios pass (reproducible: eval/run_eval.py)

Track 1 requirement Measured
Cross-session recall under noise allergy + diet recalled after 13 unrelated turns and a session switch - 182 tk vs 512 tk prompt
Timely forgetting employer change fires a supersede op - zero stale-fact leakage in a fresh session
Efficient storage after 32 messages: 48 tk store vs 849 tk raw history (94% smaller)
Consolidation sleep cycle merges 3 fragments into 1 dense memory (98 -> 74 tk)
Critical recall in a limited window peanut allergy surfaces at cosine 0.31 via the importance rescue floor

Full method and tables: docs/evaluation.md

Server-side action policy gate

A standing procedural memory can deny a risky action before generation: the verdict (deny / require-approval / preconditions) is computed server-side with action+resource matching, injected into the prompt, carried with a dry-run proposed_tool_call and dispatch: executed=false, and persisted in the per-turn audit. 20 deterministic cases: 20/20, deny precision 100%, false-block 0% (docs/evaluation.md).

Ablations — every mechanism justified by a measured failure

Remove… What breaks (measured, real API)
importance-rescue floor (score = cosine only) peanut allergy at cosine 0.246 is silently dropped for a "trail snack" query
LLM arbitration (append-only store) employer change stored as a new fact — stale belief recalled next to the new one, 2 contradictory facts live
sleep cycle fragments never merge and the store only grows (with it on: 3 fragments → 1, store 98 → 74 tk)

A plain vector-RAG memory is the first two rows failing at once. Reproduce with python3 eval/run_ablation.py semantic_only / no_arbiter — full table in docs/evaluation.md.

How to test (judges)

Five-step verification ladder (10 s → 10 min): JUDGING.md

Inspiration

Every LLM agent wakes up with amnesia. Context windows keep growing, but stuffing full chat history into every prompt is expensive, slow - and still forgets everything when the session ends. Human memory works differently: we distill experience into durable traces, strengthen what we use, revise what changed, and consolidate while we sleep. ENGRAM brings that architecture to Qwen agents.

What it does

  • Extracts typed memories (preference / semantic / procedural / episodic) with model-scored importance from every user turn
  • Recalls under a strict ~800-token budget with a transparent hybrid score: 0.55*semantic + 0.18*recency + 0.17*importance + 0.10*usage, per-type half-lives, and a rescue floor so safety-critical memories (a peanut allergy) surface even at low similarity
  • Revises beliefs: embeddings shortlist neighbors, an LLM arbiter rules duplicate / replaces / distinct - "I changed jobs" supersedes the stale fact instead of duplicating it
  • Sleeps: a consolidation cycle merges similar fragments into dense semantic knowledge (union-find clusters at cos>=0.58, within-type) and forgets low-retention traces
  • Remembers across sessions: new session, empty context - the agent still knows you
  • Visualizes everything live: a canvas memory constellation shows recall beams, reinforcement pulses, supersede flashes and consolidation vortexes; every recall streams its score components to the UI, so retrieval is explainable
  • Mounts anywhere: the same store is exposed as an MCP server (engram_remember / engram_recall / engram_forget / engram_sleep) so any MCP-capable agent can share this memory

How we built it

100% Qwen Cloud (Alibaba Cloud Model Studio): qwen3.7-plus for streaming conversational reasoning grounded on the injected MEMORY block; qwen3.6-flash for extraction, contradiction arbitration and consolidation (thinking off, JSON-only, temp 0.1); text-embedding-v4 for 256-d vectors. The backend is pure Python stdlib - zero pip dependencies - because production is a 1-core / 728 MB CentOS 7 box: threaded HTTP+SSE server, SQLite (WAL) with float32 vector blobs, nginx TLS + rate limiting, systemd with a 180 MB memory cap. The frontend is a single self-contained HTML file: no frameworks, embedded fonts, canvas force layout.

Challenges we ran into

  • Contradiction detection cannot be a similarity threshold. Measured on text-embedding-v4: "vegetarian" vs "eats meat now" scores 0.76 (contradiction), while "vegetarian" vs "peanut allergy" scores 0.60 (both true). Cosine alone cannot separate them - so an LLM arbiter decides duplicate/replaces/distinct over an embedding-shortlisted candidate set.
  • Consolidation thresholds were calibrated from real pair measurements (same-topic 0.50-0.75, unrelated <0.48 -> cluster at 0.58, within-type only, so a diet preference is never vacuumed into a travel plan).
  • Zero-dependency constraint: SSE streaming, retry/backoff, vector math and MCP JSON-RPC are hand-rolled on stdlib; the host's SQLite even predates UPSERT.

Accomplishments we're proud of

A cooking question quietly respects a peanut allergy stated once, sessions ago. A job change cleanly supersedes the old belief. Three Tokyo-trip fragments consolidate into one dense memory while the store shrinks and context stays ~90% smaller than full history - all visible, all explainable, all running on free-tier Qwen Cloud quota on a 728 MB server.

What we learned

Memory quality is an engineering problem more than a prompt problem: budgeted retrieval, measured thresholds, explicit belief revision and an audit trail (superseded_by / consolidated_into) matter more than any single clever prompt.

What's next for ENGRAM

Per-team memory namespaces, reflective insight memories distilled from episodic clusters, smarter forgetting policies, and packaging the MCP server for one-line install.

Built With

Share this project:

Updates