Skip to content

JrKrishh/nova-memory

Repository files navigation

🧠 Nova Memory — a brain-inspired memory engine for AI agents

Submission for the Global AI Hackathon Series with Qwen Cloud · track: MemoryAgent

Demonstrated by "Remember Me" — a playable 2D game where an AI companion genuinely remembers you across days.

🎬 Watch the 3-min demo — every visual (Wan 2.2) and voice (Qwen3-TTS) in it was generated on Qwen Cloud.

Most AI "memory" is a junk drawer: dump every message into a vector database, retrieve by similarity. It grows without bound, drowns in trivia, and never forms real understanding of the user.

Nova Memory builds memory the way the brain does — using Complementary Learning Systems theory from neuroscience — and it directly implements the three things this track asks for:

MemoryAgent track pillar How Nova Memory does it
Efficient memory storage & retrieval Salience-gated writes + hybrid retrieval (semantic + BM25 keyword) + LLM reranking
Timely forgetting of outdated information "Sleep" consolidation supersedes stale facts (moves, job/goal changes); low-salience details decay; the store stays bounded
Recalling critical memories within limited context Reconstructive recall injects only the top-k relevant memories — a few hundred tokens, never the whole history

Architecture

🎮 The demo: Remember Me (playable 2D game)

You're a new crew member on a quiet space station. Nova, the station AI, gets to know you across several in-game days — powered entirely by Nova Memory:

Nova's Station

  • Walk the station (WASD/arrows), talk to Nova (E) — every conversation is salience-gated into memory
  • Step into the Sleep Pod to end the day → Nova consolidates: raw moments merge into durable memories, small talk fades away (you see the counts)
  • Next morning Nova greets you weaving in what she remembers — your name, your coffee, your deadline
  • The Memory Terminal prints Nova's heartfelt "memory of you" — everything she kept, nothing she shouldn't have

A real exchange from testing — after one day and a sleep:

"Good morning, Boopathi! ☕ Just brewed a fresh pot of filter coffee — hope it's as strong and steady as your Nova Memory engine must be getting ahead of that July 9th hackathon deadline…"

Four separate memories, recalled and woven into one natural greeting — while the throwaway small talk from the same conversation was correctly forgotten.

📦 Nova Memory is an engine, not just a demo

The same library drops into any agent in five lines:

from nova_memory import NovaMemory

mem = NovaMemory("user42")
mem.encode("I'm Maya, allergic to peanuts, training for an October marathon")  # salience-gated write
facts = mem.recall("what should I avoid feeding Maya?")   # hybrid retrieval + rerank
mem.consolidate()                                          # "sleep" → durable user-model
mem.save()

The identical engine that powers Nova also powers:

  • an elderly-care companion that remembers family names, routines, and medications,
  • a tutor that remembers each student's weak areas across months,
  • a support agent that remembers the customer's setup and past issues.

Three included surfaces, one engine:

URL Surface
/world Remember Me — the playable 2D game
/game The chat-style companion
/ Technical dashboard — watch episodic → semantic memory form live

🔬 How it works (brain → code)

Brain mechanism Nova Memory implementation
Salience gate (dopamine / prediction-error) An LLM pass keeps only durable, specific facts — trivia never enters memory
Episodic store (hippocampus) Fast raw facts with concrete specifics (dates, names, places), embedded
Consolidation ("sleep" / replay) Merges episodic → clean semantic user-model, superseding outdated facts
Memory strength & decay ("use it or lose it") Every memory has a strength that decays when unused; salient + rehearsed memories decay far slower
Forget ≠ erase (retrieval failure vs. deletion) Faded memories go dormant — hidden from recall but kept. A strong, specific cue reactivates them ("a smell brings it back")
Rehearsal / reconsolidation Recalling a memory strengthens it and revives dormant ones — like the brain
Reconstructive recall Hybrid semantic+BM25 retrieval over active memories → LLM rerank → tiny context

The differentiator: most memory systems either keep everything (bloat) or delete (loss). Nova Memory does what brains do — forgets without erasing. A memory it hasn't used in "weeks" fades out of recall, yet the trace persists and resurfaces the moment you give it the right cue. Verify it yourself: python test_bio.py.

📊 Benchmarked honestly

Efficiency & coherence (120 noisy turns with contradicting updates): Nova Memory kept 13 memories vs 120 for a store-everything baseline (9× leaner, gap compounds forever) at equal recall accuracy (6/6) — and when asked "what do you know about me?", Nova Memory produced a clean user-model while the baseline returned noise ("you said 'haha that meme'…"). Reproduce: python bench_scale.py.

LoCoMo (public long-term-memory benchmark, 419-turn conversation): our first version scored 10% — the forgetting was too aggressive. We tuned retention and added hybrid retrieval + reranking, reaching 50% vs 42% for the keep-everything baseline on the same run (small sample: 12 QA — we report it as competitive, not superior; systems that store far more, like Mem0, score higher on exhaustive-recall benchmarks by design). That tradeoff is deliberate: this track rewards efficiency and timely forgetting, not hoarding. Reproduce: python locomo_bench.py.

☁️ Built on Qwen Cloud (Alibaba Cloud)

Every cognitive step runs on Qwen Cloud (DashScope, OpenAI-compatible):

  • qwen-plus — salience gate, consolidation, reranking, Nova's dialogue
  • text-embedding-v3 — memory encoding & recall (1024-d)

There is no fine-tuning — the memory architecture is the innovation. 👉 qwen_client.py is the Alibaba Cloud integration (proof of Alibaba Cloud service usage).

🚀 Quickstart

pip install -r requirements.txt
echo 'sk-your-dashscope-key' > .qwen_key      # Alibaba Cloud Model Studio → API-KEY
python server.py                               # → http://localhost:8770/world

Play: tell Nova about yourself → sleep pod → watch her remember you tomorrow → Memory Terminal for her farewell note. Press M anytime to see exactly what she remembers (full transparency — a thing black-box memory products don't give you).

Repo structure

nova_memory.py     public library API  (from nova_memory import NovaMemory, Agent)
memory.py          the CLS engine — salience gate / hybrid recall / consolidation / forgetting
agent.py           conversational wrapper
qwen_client.py     Qwen Cloud client (chat · embeddings · rerank)   ← Alibaba Cloud proof
server.py          demo server (game + companion + dashboard)
web/world.html     Remember Me — playable 2D game
web/game.html      chat companion UI
web/index.html     technical memory dashboard
bench_scale.py     efficiency/coherence benchmark vs naive memory
locomo_bench.py    LoCoMo long-term-memory benchmark harness
docs/              architecture diagram · screenshots · video script

License

MIT — see LICENSE.

About

No description, website, or topics provided.

Resources

License

Stars

0 stars

Watchers

0 watching

Forks

Releases

No releases published

Packages

 
 
 

Contributors