Skip to main content

How SharedMemory Works

SharedMemory is a multi-database hybrid system that combines the strengths of four specialized storage engines.

The Four Pillars​

1. PostgreSQL — Source of Truth​

Every memory entry, user, volume, agent, and document is recorded in PostgreSQL. This is the authoritative record — if there's ever a conflict between databases, Postgres wins.

2. Neo4j — Knowledge Graph​

The structured representation of knowledge. When you write "John is a senior engineer at Google who knows React", Neo4j stores:

(John:Entity:Person) -[:WORKS_AT]-> (Google:Entity:Organization)
(John:Entity:Person) -[:HAS_SKILL]-> (React:Entity:Technology)
(John:Entity:Person) -[:HAS_FACT]-> (Fact: "Senior engineer at Google")

3. Qdrant — Vector Search​

Every piece of text is embedded as a 384-dimensional vector using all-MiniLM-L6-v2. This enables semantic similarity search — finding relevant memories even when the exact words don't match.

4. Redis — Job Queue & Cache​

BullMQ runs on Redis for reliable async processing. Also used for embedding cache and rate limiting.

Query Flow​

When you ask SharedMemory a question:

Query: "What is John's experience with cloud computing?"
                    │
    ┌───────────────┼───────────────┐
    ▼               ▼               ▼
 Qdrant         Neo4j Entity     Postgres
 Semantic       Extraction →     Fallback
 Search         Graph Traversal  (recent entries)
    │               │               │
    └───────┬───────┘───────────────┘
            ▼
    Combined Context → LLM Synthesis → Response + Sources
  1. Entity extraction — LLM identifies entities in the query
  2. Parallel search — Qdrant semantic search + Neo4j graph traversal + Postgres fallback
  3. Context assembly — Results merged and ranked
  4. LLM synthesis — Answer generated with full source attribution

Write Flow​

  1. Classify → Embed → Guard check → Index → Extract → Broadcast

Volume Isolation​

All data is scoped to volumes:

  • Each volume has its own Qdrant collection (memory_entries_{volume_id})
  • Neo4j nodes carry volume_id properties for filtering
  • Postgres queries always include WHERE volume_id = $1
  • No data leaks between volumes