Raven Memory

The agent doesn't find memories — it resonates with them.

Comment

🦅 Raven-Memory

Adaptive Memory Field for Agentic Systems

Track 1: MemoryAgent · Qwen Cloud Hackathon

https://github.com/annatchijova/raven-memory

https://annatchijova.github.io/vigia/raven-memory-2.html

"The agent doesn't find memories — it resonates with them."

Elevator Pitch

Most RAG-based agents do this: query → embed → top-k cosine search → return k documents. That's a database lookup, not memory. No dynamics, no contradiction detection, no reinforcement, no pruning — every recall is as shallow as the last.

raven-memory replaces the lookup with a field. Every stored vector becomes a cell in a Voronoi diagram. Recall starts at the nearest cell and BFS-expands through the neighbourhood, scoring each hit dynamically. Memories live in one of three states, and when two memories contradict each other, the field collapses around the truth.

Architecture

               ┌─────────────────────────────────────────────────┐
               │              Adaptive Memory Field               │
               │                                                   │
  query ──────►│  KDTree        BFS hop       Ternary scoring     │──► top-k results
  embedding    │  seed cell ──► expansion ──► sim × state × decay  │
               │                    │                              │
               │         RESONANT ──┤── INHIBITORY links          │
               │         (amplify)  │   (silence contradictions)  │
               │                    │                              │
               │              STDP updates                         │
               │         (co-activation strengthens links)         │
               └─────────────────────────────────────────────────┘

Flagship Behavior: Collapse Around Truth

Two contradictory memories exist, both NEUTRAL, nearly tied:

Before reinforcement:
  VIGIA is deterministic   [NEUTRAL]  score=0.447
  VIGIA uses ML            [NEUTRAL]  score=0.441   ← nearly tied

User reinforces the first one ↓

After reinforcement:
  VIGIA is deterministic   [REINFORCED]  score=1.493  ← dominates
  VIGIA uses ML            [NEUTRAL]     ← silenced (INHIBITORY)

The field collapsed around the validated truth. The INHIBITORY link was already present (created automatically when the conflicting claim was stored). Reinforcement just activates it.

Key Mechanisms

Mechanism What it does
KDTree + k-NN graph Each stored vector becomes a Voronoi cell. Recall starts at the nearest cell and BFS-expands through the neighbourhood.
Ternary states REINFORCED ×1.5 / NEUTRAL ×1.0 / FORGOTTEN ×0.0. States multiply the base cosine score.
Hop decay score × exp(−λ × hop_distance). Distant cells are penalised, not cut off.
STDP dynamics Co-activated pairs strengthen (LTP). Absent pairs weaken (LTD). Mirrors Hebbian learning.
Ternary cell links RESONANT amplifies neighbours. INHIBITORY silences contradictions. Created automatically for same-topic conflicting claims.
Recency bonus 24-hour half-life additive term rewards recently-accessed memories.
REINFORCED immunity A validated truth cannot be silenced by an unvalidated claim during BFS expansion.
Stylometric fingerprinting Detects if a memory's writing style doesn't match the registered author; auto-degrades to FORGOTTEN.
Audit hash-chain Every recall is cryptographically chained (SHA-256) — tamper-proof provenance.
Sleep consolidation Episodic memories cluster offline and merge into semantic nodes with a recall-frequency-weighted centroid.

The Math: Scoring & Stability

Scoring Formula:

score = (cosine_sim × state_boost × exp(−λ·hop))
      + resonant_boost
      + synaptic_weight × 0.3
      + exp(−ln2 · age / 24h) × 0.05

Memory Stability Score (MSS):

MSS = 1.5R / (1.5R + N)
  • MSS → 1.0 means the agent has a stable, validated worldview.
  • MSS = 0.0 means everything is unconfirmed noise.

How We Built It

  • Core: Python 3.12, FastAPI + Uvicorn (REST + WebSocket), SQLite (with optimized indices on cell_id, layer, author_id, state).
  • Math & ML: NumPy/SciPy for KDTree and spectral math, scikit-learn for agglomerative clustering.
  • AI & Cloud: Qwen Cloud (text-embedding-v3, qwen-max), Docker, Alibaba Cloud ECS (Singapore).
  • Embeddings Fallback: local all-MiniLM-L6-v2 → Qwen Cloud → deterministic SHA-256 dummy.

Challenges We Ran Into

  • Lazy KDTree Rebuild: Keeping it dirty-flagged (only before recall(), not on every store()) without ever serving a stale tree.
  • Persistence on Restart: Reconstructing _points and the topic index from the DB on engine restart — a common oversight in similar systems that we caught and fixed.
  • Bounding STDP Growth: Repeated co-activation can currently climb without an upper cap. Documented as a known limitation.
  • sklearn API Drift: Navigating deprecated parameters by using metric="precomputed" + cosine_distances().

What's Next

  • Cap STDP synaptic growth with a decay/normalization term.
  • Expose a /consolidate endpoint so sleep consolidation runs without restarting the engine process.
  • Stratified spectral fields per memory layer, once corpus size justifies the added complexity.

Project Structure

raven-memory/
├── memory_engine.py       # Core adaptive memory field (KDTree, STDP, audit)
├── qwen_client.py         # Qwen Cloud client + MemoryAgentOrchestrator
├── api_server.py          # FastAPI REST server (Swagger at /docs, WebSocket /ws)
├── demo_killer.py         # Gradio demo — 4 tabs, live MSS, collapse visualization
├── sleep_consolidator.py  # Offline consolidation (agglomerative clustering)
├── test_suite.py          # 15 integration tests (all P0 behaviors)
├── demo_stress_test.py    # Multi-phase adversarial stress test
├── run_all.py             # One-command evaluation runner
└── requirements.txt

Quickstart

# 1. Install dependencies
pip install -r requirements.txt

# 2. Run all tests (no API key required)
python run_all.py

# 3. Launch Gradio demo
python run_all.py --demo
# → http://localhost:7860

# 4. Launch REST API
python run_all.py --api
# → http://localhost:8000/docs

With Qwen Cloud (full LLM responses):

export DASHSCOPE_API_KEY=your_key_here
python run_all.py --demo

Note: Without a key, the system runs fully offline with deterministic SHA-256-seeded embeddings and an offline LLM stub. All memory mechanics are identical.

🌐 REST API Endpoints

POST   /memories                    # Store a memory
GET    /memories                    # List with filters (layer, state, limit)
GET    /memories/{id}               # Get a single memory
POST   /recall                      # Semantic recall with field dynamics
POST   /memories/{id}/reinforce     # Set state = REINFORCED
POST   /memories/{id}/forget        # Set state = FORGOTTEN
POST   /cell-links                  # Create RESONANT/INHIBITORY link
GET    /graph                       # Export full memory graph (nodes + edges)
GET    /stats                       # Engine stats + MSS
GET    /audit                       # Hash-chain audit trail
GET    /alerts                      # Forensic tamper alerts
WS     /ws                          # Real-time event stream

Authors & License

Anna Tchijova
License: Apache 2.0

Qwen Cloud Hackathon · Track 1: MemoryAgent · Deadline: July 9, 2026

🦅✨

Built With

Share this project:

Updates