BrainDB Memory Database

Give LLM agents persistent, connected memory with searchable facts, provenance, and automatic upkeep.

Source repo
dimknaf/braindb
Stars
★ 117
Last updated
1mo ago
License
Apache-2.0
Primary language
Python

At a glance

How it runs
Self-hosted serviceWeb appAgent plugin / skill
Works with
Universal · cross-platformClaude CodeOpenAI API (Partial support)
Cost
Free software; you pay for model usage
Setup effort
Medium · a few setup steps
You'll need
Docker Compose v2.20+PostgreSQL with pg_trgm and pgvector extensionsLLM provider credentials for the internal agentShell / CLINetwork accessLocal filesystem
Typical use
Teams building multiple LLM agents can use the REST API to store and retrieve persistent, traceable facts and inferences.
Not a fit if
  • Teams that need a fully hosted cloud service
  • Teams requiring data to stay local while using no remote model
Maintenance
Commits in the last 6 monthslast commit 2026-10-12latest release v0.11.1 (2026-10-12)

What does this agent do, and when should you use it?

BrainDB is a PostgreSQL-backed memory database and REST API for typed entities such as thoughts, facts, sources, datasources, and rules. Its FastAPI service exposes entity management, fuzzy and semantic retrieval, graph traversal up to three hops, temporal decay, and rule injection. The built-in agent uses the OpenAI Agents SDK and accepts natural-language requests at /api/v1/agent/query, with DeepInfra, NVIDIA NIM, and other OpenAI-compatible providers configurable. Docker Compose can also run a file-watching ingestion service, an automatic wiki-maintenance scheduler, and a read-only browser frontend. The services and data run in the user's Docker/PostgreSQL environment; the internal agent sends model requests to the configured provider.

Create entities through endpoints such as /api/v1/entities/thoughts, /facts, /sources, /datasources, and /rules, then connect them with /api/v1/relations. POST /api/v1/memory/context combines pg_trgm keyword matching with embedding-based semantic matching, expands results up to three relation hops, ranks them, and injects always-on rules. Files placed in data/sources/ are chunked and processed by the watcher, which extracts facts and links them to their source with derived_from relations. wiki_scheduler finds uncovered entities and maintains sourced wiki pages. The built-in agent uses /api/v1/agent/query to choose tools for natural-language recall or updates and return a summary; the read-only frontend supports wiki reading, graph exploration, operations monitoring, and asking the agent.

  1. Teams building multiple LLM agents can use the REST API to store and retrieve persistent, traceable facts and inferences.
  2. Researchers who collect Markdown source material can drop files into data/sources/ for automatic fact extraction with provenance links.
  3. Product or operations teams that need recall by keyword and relationship can call /api/v1/memory/context for a ranked graph neighborhood.
  4. Users who want to query or update memory in natural language instead of orchestrating individual endpoints can call /api/v1/agent/query.
  5. Teams that want accumulated knowledge organized into sourced wiki pages can enable wiki_scheduler and review results in the frontend.

Key setup facts

Pulled from the install and usage notes below. The project README has the current values.

Install / run
  • docker compose up -d --build
Ports
8000 · 8642
Environment variables
LLM_PROFILE DEEPINFRA_API_KEY DATABASE_URL
Config files
.env.example .env
Install notes cover
Docker

How do you install or deploy this agent?

You need Docker Desktop or Docker Engine and Compose v2.20+. The default configuration starts a bundled PostgreSQL database. To use the internal agent, also configure credentials for the selected model provider. These commands start the API, watcher, wiki scheduler, frontend, and default database:

git clone https://github.com/dimknaf/braindb.git
cd braindb
cp .env.example .env

In .env, keep the default LLM_PROFILE=deepinfra and set DEEPINFRA_API_KEY, or configure another supported provider. Create the network and start the services:

docker network create local-network
docker compose up -d --build

The health endpoint is http://localhost:8000/health, API docs are at /docs, and the read-only frontend defaults to http://localhost:8642. To use an external PostgreSQL database, set DATABASE_URL and ensure pg_trgm and pgvector are enabled.

How do you use this agent?

The API defaults to http://localhost:8000. Submit a natural-language request to /api/v1/agent/query, for example:

curl -X POST http://localhost:8000/api/v1/agent/query \\
  -H "Content-Type: application/json" \\
  -d '{"query":"What do you know about recent projects?"}'

Drop Markdown files into data/sources/ for automatic watcher ingestion; call /api/v1/memory/context for direct retrieval, or use the entity and relation endpoints to manage records. Open the frontend at http://localhost:8642. Claude Code users can also install the repository's skills/braindb/SKILL.md or skills/braindb-agent/SKILL.md skill.

What are this agent's strengths and limitations?

Pros
  • Uses PostgreSQL with pg_trgm and pgvector for text and semantic retrieval, avoiding a separate graph database to operate.
  • Typed entities, provenance, and explicit relations support traceability; retrieval can include graph neighborhoods and temporal decay.
  • Offers REST endpoints, a natural-language internal agent, automatic file ingestion, and wiki maintenance workflows.
  • Provider configuration supports DeepInfra, NVIDIA NIM, and OpenAI-compatible endpoints, including local vLLM servers.
Limitations
  • Requires deploying Docker Compose services and a PostgreSQL environment; the default setup also requires creating local-network.
  • The internal agent, file ingestion, and wiki maintenance call the configured LLM service and may incur API charges; local models must be run and configured separately.
  • External PostgreSQL must have pg_trgm and pgvector; migrations need permission to create extensions unless an administrator installs them first.
  • The README does not document authentication, authorization, or tenant isolation, so it does not establish the security boundary for exposing the API publicly.

How does this agent compare with similar options?

The README compares BrainDB with RAG, general graph databases such as Neo4j and Memgraph, and Markdown-file memory. It emphasizes persistent typed entities, relations, graph-neighborhood retrieval, and temporal decay; compared with general graph databases, it uses an HTTP API and PostgreSQL extensions as its primary deployment model.

Key facts side by side with the most closely related agents.

Agent Source review Form / cost Stars Updated Language Full support on
BrainDB Memory Database This agent 59 · Major gaps Self-hosted serviceFree + model costs ★ 117 1mo ago Python Claude Code
SimpleMem: Efficient Lifelong Memory for LLM Agents 47 · Major gaps Library / SDKFree + model costs ★ 3.9k 4mo ago Python ChatGPT · Claude Code
qKnow Enterprise Knowledge Platform 43 · Major gaps Self-hosted serviceFreemium ★ 300 4d ago Java —
Mnemosyne 71 · Some gaps CLIFree ★ 3.7k 2d ago Python Codex · Claude Code

How does FollowAgents rate this agent?

FollowAgents source review · FARS-2.1
Major gaps
59/ 100 5-point scale 3.0 / 5
Trust 13/29
Reliability 8/14
Adaptability 12/18
Convention 13/18
Effectiveness 9/13
Verifiability 4/8
Why each dimension lost points
Trust13 / 29 · 2.2/5

The repository shows configurable model backends, environment-variable credentials, activity logging, read-only SQL, failed-file isolation, and wiki-job recovery, making some data flows and recovery paths visible. Entity provenance distinguishes user-stated, agent-inference, document, and third-party. Scores are reduced because agent tools include deletion and writes, background ingestion and maintenance run automatically, and a skill offers auto-start instructions; the evidence does not show per-action confirmation or strict permission isolation. Retention, transfer, and deletion policies for sensitive data are also unspecified. Dependencies are pinned but no security audit or mitigation is shown; provenance labels aid traceability but do not establish correctness.

Reliability8 / 14 · 2.9/5

A version, configuration tests, CI workflow, isolated test-stack guidance, and startup recovery logic provide some reliability evidence, and failures are logged and returned as explicit HTTP errors. Scores are reduced because the README's braindb-agent skill describes a different default model from its table and other materials, while the claimed 21 tools may use a different counting scope from the source list. Remote model and database availability depend on external services, and the agent smoke test is explicitly described as potentially slow or flaky.

Adaptability12 / 18 · 3.3/5

The README and skills clearly target developers, Claude Code, and external LLM clients, and cover local and hosted OpenAI-compatible services, bundled or external PostgreSQL, and both API and agent workflows. Scores are reduced because the skill's trigger language is broad, including every session and personal information, while permission boundaries, confirmation behavior, and deployment security guidance are incomplete.

Convention13 / 18 · 3.6/5

The repository provides a project structure overview, endpoint table, installation and verification steps, multiple curl examples, troubleshooting notes, an explicit Apache-2.0 license, and a package version. Scores are reduced because a change history is not evident in the supplied material, publisher identity is unknown, and no maintainer or support/update responsibility is clearly established. The README and skill also disagree about the default model.

Effectiveness9 / 13 · 3.5/5

Typed entities, graph relations, fuzzy and semantic retrieval, temporal decay, an HTTP API, an internal agent, and wiki maintenance provide substantial capabilities beyond basic retrieval, with directly usable endpoint and command examples. Scores are reduced because the watcher and scheduler can call LLMs continuously; cost control mainly means disabling services or using a local model, with no evidenced default budget cap or per-run cost approval. Outcome quality and workflow benefits are mostly asserted in project documentation.

Verifiability4 / 8 · 2.5/5

Endpoints, configuration, skills, and some agent/API source can be compared, and the CI and test configuration describe concrete coverage. Provenance fields distinguish user statements, inferences, and document sources. Scores are reduced because many retrieval-quality, latency, cost, and compatibility claims appear in the README without supporting measurements or complete implementation evidence in this sample; some relevant configuration and workflow files are outside the supplied packet, limiting corroboration.

Risks and how to mitigate them
  • Verify the default LLM profile and model against your credential setup; the braindb-agent skill conflicts with the README.
  • The watcher and wiki_scheduler can call models and write to the database in the background; confirm data scope, cost controls, and how to stop them before deployment.
  • The agent exposes delete and write operations; restrict API network access and arrange backups and recovery for important data.
Evidence confidence: Low Reviewed Nov 11, 2026 Reviewed revision 98d35154a9e2
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/braindb.svg)](https://followagents.com/en/agents/braindb)
<a href="https://followagents.com/en/agents/braindb"><img src="https://followagents.com/badge/braindb.svg" alt="FARS review"></a>

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

  1. v0.11.1 v0.11.1 — Faster recall on low-resource devices, same results
    Release notes excerpt
    Headline Recall stays fast on densely connected memories and on low-resource devices, with exactly the same results. The graph step no longer lists every path through the graph, so it takes about a second instead of up to minutes and writes next to no temporary files. The agent's database tools no longer hold up the rest of the API while they run, and reads no longer re-index stored text. Fixed …
    View on GitHub ↗
  2. v0.11.0 v0.11.0 — JEV: one-token decisions inside the agent's conversation
    Release notes excerpt
    Headline This release adds JEV. Some steps in BrainDB are really yes/no questions: is this part of a document useful, is this linked item worth following, is this fact about the page's subject. JEV asks the model that question inside the conversation that needs it and reads the answer from the probability of a single token. Items it rejects never enter the conversation, so they are not paid for again in later turns. …
    View on GitHub ↗
  3. v0.10.0 v0.10.0 — Wiki pipeline hardening: terminating writer loop, self-healing jobs, editable headers
    Release notes excerpt
    Headline The wiki pipeline is now dependable under long, unattended runs. The writer loop always terminates, crashed and restarted jobs recover on their own, and the page header is editable instead of frozen after the first write. Also in this release: a reasoning-effort knob for the wiki agents that cuts latency several-fold on self-hosted models, a per-call LLM timeout so slow local writes are no longer abandoned mid-flight, and both agents can now see how big a page is before deciding what to do with it. Added …
    View on GitHub ↗

FAQ

Do I have to pay for a model provider to use BrainDB?
The software has a self-hosted path and can be configured for local vLLM. Remote providers such as DeepInfra require credentials and may charge for usage.
Can BrainDB use an existing PostgreSQL database?
Yes. Set DATABASE_URL for a container, host, or remote database and enable pg_trgm and pgvector. Migrations need permission to create the extensions, or an administrator must install them first.
Does file ingestion preserve source provenance?
Yes. The watcher extracts atomic facts from files and links them back to the source with derived_from relations. Re-ingesting identical content is idempotent.
Can I run the database and API without automatic maintenance?
Yes. Docker Compose lets you scale wiki_scheduler or the watcher to zero, which stops the corresponding automated workflow.
Is BrainDB Memory Database open source?
Yes. The source code is on GitHub (dimknaf/braindb) under the Apache-2.0 licence.
Is BrainDB Memory Database safe to use?
FollowAgents' FARS review (Nov 11, 2026) scored BrainDB Memory Database 13/29 on trust and safety. None of the eight safety controls the review checks for was missing outright.
Is BrainDB Memory Database still maintained?
Development has slowed: the latest commit on GitHub is from 2026-10-12, within the last six months but not the last 30 days. The latest release is v0.11.1 (2026-10-12).
Who makes BrainDB Memory Database?
BrainDB Memory Database is published on GitHub by the account dimknaf. FollowAgents has not verified which person or company is behind that account.
Was this page helpful?
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts