v1 — Core Memory API

Docs

This documents what's actually built and running today: a self-hosted, Neo4j-backed memory core with entity resolution and hybrid retrieval. Adaptive retrieval, emotional embeddings, and consolidation are staged for later phases and not covered here.

// 01

Setup

Requires Node.js 20+, Docker, and an OpenAI API key.

cd backend
cp .env.example .env      # add your OPENAI_API_KEY
npm install
npm run db:up             # start local Neo4j via Docker
npm run db:init           # apply constraints + indexes
// 02

Client

One class, four operations.

import { SupmemClient } from "@supmem/backend"

const client = new SupmemClient()
await client.init()

const { id } = await client.add(userId, "Ada works at Analytical Engines as a mathematician.")
const results = await client.search(userId, "Where does Ada work?")
const memory = await client.get(id)
await client.delete(id)
// 03

How add() works

Each call runs LLM entity/relationship extraction and embedding generation in parallel, then writes everything in a single transaction: a Memory node, resolved/deduped Entity nodes (matched on user + normalized name + type), and MENTIONS / RELATES_TO edges between them.

// 04

How search() works

Runs vector KNN (semantic) and fulltext (keyword) search in parallel, min-max normalizes each channel's scores independently, then merges by weighted sum (default 0.6 vector / 0.4 keyword). This is intentionally simple — full 5-channel RRF fusion with temporal, emotional, and graph channels is on the roadmap.

// 05

Known v1 limitations

  • Vector search over-fetches then filters by user — no native per-user pre-filter in Community Edition at this version
  • delete() removes the memory node only; orphaned entities aren't cleaned up yet
  • No temporal versioning — deletes are permanent
  • No adaptive learning, emotional tagging, or memory consolidation yet