MEMORIUM — the enemy remembers you

Play it live: memorium.ironyaditya.xyz

A browser arena shooter where the AI opponent has persistent memory. Every run you play is summarized and stored in Cognee as a knowledge graph; before your next run the enemy recalls who you are — your favorite side of the map, your weapon habits, your accuracy, whether you heal — and an LLM turns that dossier into a counter-strategy. Attempt 1 fights a stranger. Attempt 10 fights someone who has been studying you.

Built for the WeMakeDevs × Cognee hackathon "The Hangover Part AI: Where's My Context?" (Cognee Cloud track).

The memory loop

 you play a 5-level run
        │  telemetry (shots, positions, heals, tasks, map)
        ▼
 narrative run summary ──► Cognee remember (add + cognify)
                                   │  builds the knowledge graph
                                   ▼
                    next run: Cognee recall (GRAPH_COMPLETION)
                                   │  "favors the left side, rifle-only,
                                   │   low accuracy, rarely heals…"
                                   ▼
                    LangGraph + Gemini → bot strategy
                                   │  weapon, stance, aggression,
                                   │  expected player side
                                   ▼
                    the bot hunts YOU differently

The memory is not flavor text — it drives gameplay. The recalled profile picks the bot's weapon, engagement stance, aggression level, and which side of the map it patrols first. Erase your memory (one button) and the enemy is dumb again.

How Memorium uses Cognee (Cognee Cloud REST)

Cognee is the core of the gameplay loop, not a side feature — the enemy's intelligence IS the memory layer. We use the full lifecycle over the REST API, with one dataset per player:

Lifecycle	Endpoint	Where it happens
remember	POST /api/v1/remember	Run end: the run's narrative summary is ingested (add + cognify) into a per-player dataset, in the background
promotion	GET /api/v1/datasets/status	The end-of-run screen polls the cognify pipeline until the graph is built. On Cloud there is no separate improve call — the remember pipeline is the promotion into permanent graph memory
recall	POST /api/v1/recall	Before each run: GRAPH_COMPLETION with a custom systemPrompt distills the player's graph into a 4-sentence combat dossier (topK tuned)
forget	POST /api/v1/forget	"Erase enemy memory" button: deletes the player's dataset, scoped by name — the enemy genuinely forgets
graph	GET /api/v1/datasets/{id}/graph	The dossier screen renders the player's actual knowledge graph (entities like "44% accuracy", "left side of the map") on a canvas — the enemy's mind, visible

remember — telemetry becomes memory

At the end of each 5-level run, the player's raw telemetry (positions, shots, accuracy, heals, tasks completed, map played) is composed into a plain-language narrative summary and ingested into that player's dataset. Ingestion runs in the background (run_in_background=true); the frontend polls the promote status while the final score screen shows, so the graph build (~10s) hides inside natural downtime.

recall — memory becomes behavior

Before each run, one recall distills the player's knowledge graph into a short combat dossier. That text feeds two consumers:

1. The "WHAT THE ENEMY REMEMBERS ABOUT YOU" panel — the player reads their own habits back.
2. A LangGraph two-node strategy graph, where Gemini converts the dossier into the bot's structured config: weapon, engagement stance, aggression level, and which side of the map to patrol first.

Memory has direct gameplay consequences: camp the left side with a rifle and lose, and next run the bot picks the counter-weapon and hunts the left side first.

forget — a real product action

The start screen's "Erase enemy memory" button calls forget scoped to the player's dataset name (never the tenant-wide flag). The enemy reverts to its dumb default — which is also how every demo starts.

graph — the memory made visible

The pre-match dossier fetches the player's dataset graph, keeps the Entity/EntityType nodes (top 60 by degree), and renders them with a canvas force layout. Nodes like 44% accuracy, 4 kills, and left side of the map are Cognee's actual extracted entities — the hybrid graph-vector memory layer, on screen.

Engineering around the memory layer

• One dataset per player — clean isolation, and forget maps to a real product action.
• Micro-memories stay in RAM, one promotion per run — the five level summaries are staged server-side; only the composed run narrative is promoted to Cognee. Between levels the bot still adapts (Gemini re-plans from profile + this run's observations) with zero Cognee calls.
• Downtime precompute — recall + strategy run in the dead time after a run ends, so the next "Start Run" answers instantly from cache instead of paying 10–40s of live recall.
• Full degradation — every Cognee call is wrapped; if the network or tenant is down the game never blocks or 500s, the bot just falls back to its last known strategy (or the default on a truly fresh player).
• Serialized promotions per player — overlapping cognify runs on one dataset can wedge the pipeline; a per-player lock keeps memory writes safe.
• Recall output guarding — raw graph dumps or LLM ramble from recall are detected and discarded; the cache keeps the last good profile so the dossier never shows node soup.

Stack

• Frontend — React + TypeScript + Phaser 3 (Vite). Scrolling 2000×1300 worlds, three maps, minimap, line-of-sight + hearing bot perception.
• Backend — FastAPI (Python, uv). LangGraph two-node strategy graph (fetch memory → decide strategy) with Gemini 2.5 Flash via Vertex AI.
• Memory — Cognee Cloud (hosted), REST via httpx.
• Scores — SQLite (stdlib) for history + leaderboard.

Run it

Backend (needs backend/.env — see backend/.env.example: Cognee Cloud API key + tenant URL, Google Cloud project for Vertex AI ADC):

cd backend
uv sync
uv run uvicorn app.main:app --port 8000

Frontend:

cd frontend
npm install
npm run dev   # http://localhost:5173

Tests: cd backend && uv run pytest · build check: cd frontend && npm run build

Try the memory (60 seconds)

1. Enter a callsign, hit Erase enemy memory — clean slate.
2. Play a run. Lose creatively: camp one corner, never heal.
3. On the next run's briefing, read the dossier — the enemy now knows your corner, your weapon, your accuracy — and look at Inside the Enemy's Mind: that graph is Cognee's live memory of you.
4. Notice the bot: it patrols your side first, picks the counter-weapon, and its aggression is tuned to how beatable you looked.