BrainDB is a memory database and REST API for LLM agents. It stores thoughts, facts, sources, documents, and behavioral rules as typed entities, connects them with explicit relations, and retrieves them through combined fuzzy and semantic search, graph traversal up to three hops, temporal decay, and always-on rule injection. An external LLM drives it over HTTP as a tool-calling target.
The design extends the LLM-wiki idea of a persistent external memory that a model reads and writes. Unlike stateless RAG, entities persist, accrue connections, and age: supports, contradicts, elaborates, derived_from, and similar_to relations link them, and retrieval returns a ranked graph neighborhood rather than a pile of chunks. Facts extracted from a document link back to their source automatically. It runs on plain PostgreSQL with pg_trgm and pgvector.
Retrieval works through keywords as the indexing layer. Each query is matched against keyword entities by trigram similarity and by embedding cosine similarity, the two signals are merged with a geometric mean, entities surface through tagged_with edges, per-query and per-keyword diversity quotas stop one hub keyword from monopolizing results, and graph traversal multiplies each hop by the edge's relevance and importance scores.
An internal agent, built on the OpenAI Agents SDK and LiteLLM, accepts plain-English requests at a single endpoint and handles recall, save, and relate operations itself. It can use DeepInfra, NVIDIA NIM, a local vLLM server, or any OpenAI-compatible endpoint such as Ollama or LM Studio.
| Entity type | Stores |
|---|---|
| thought | inferences, hypotheses, subjective observations |
| fact | objective information with a certainty score |
| source | URLs and external references |
| datasource | full documents or files |
| rule | behavioral guidelines; always_on rules inject into every context call |
Features
- Typed entities: five entity types sharing keywords, importance, provenance (user-stated, agent-inference, document, third-party), notes, timestamps, and access counts
- Relations: typed edges with relevance and importance scores that drive graph traversal
- Hybrid search: pg_trgm fuzzy matching combined with pgvector embeddings via geometric-mean scoring
- Context retrieval: POST /api/v1/memory/context runs fuzzy search, graph expansion, decay, and ranking in one call, with multi-query input
- Temporal decay: stale items fade while recently accessed ones stay prominent
- Rule injection: always-on rules join every context response
- Internal agent: natural-language queries at /api/v1/agent/query with pluggable LiteLLM providers
- File ingestion: a watcher sidecar picks up files dropped into data/sources/ and creates datasource entities
- Wiki maintenance: a scheduler sidecar maintains wiki articles automatically
- Read-only SQL: SELECT/WITH queries over the memory store via the API
- Deployment: Docker services (API, watcher, wiki scheduler, read-only browser UI) with a bundled Postgres or your own instance, Swagger UI, and automatic migrations
