jchristn77/recalldb-server repository overview

⁠The persistence and retrieval layer your RAG pipeline is missing.

Quick Start⁠ · API Docs⁠ · SDKs⁠ · Search⁠ · Changelog⁠

⁠The Problem

You're building a RAG pipeline. You need to store embeddings, but you also need the raw content, chunk positions, content types, labels, tags, hashes, and ETags. You need multi-tenant isolation. You need filtering that goes beyond "nearest neighbor."

So you bolt pgvector onto Postgres, write migration scripts, hand-roll a chunking schema, build an API layer, add auth, wire up metadata tables, and six weeks later you have a fragile bespoke system that solves one project's needs.

RecallDB is the architecture you'd build if you had the time to do it right.

⁠Why RecallDB

Most vector databases store embeddings and call it a day. RecallDB stores the complete context your AI application needs to retrieve, rank, and act on information:

This isn't a thin wrapper around pgvector. It's an opinionated persistence schema that normalizes how AI-ready data is stored, indexed, and retrieved, so you stop reinventing the storage layer for every project.

⁠What You Get

• Multi-tenant isolation — tenants, users, credentials, and collections are fully scoped. One deployment serves many clients.
• Per-collection vector tables — each collection gets its own Postgres table with dedicated HNSW indexes (m=16, ef_construction=64). No noisy-neighbor problems.
• 5 distance metrics — cosine similarity, cosine distance, Euclidean similarity, Euclidean distance, inner product. Pick what fits your embedding model.
• Compound search queries — combine vector similarity, label filters, tag conditions, content term matching, and date ranges in a single request.
• Bring your own embeddings — no vendor lock-in to any embedding provider. Use OpenAI, Cohere, Ollama, or anything that outputs a float array.
• 40+ REST endpoints — full CRUD for tenants, users, credentials, collections, documents, labels, and tags.
• SDKs in C#, Python, and JavaScript — typed clients ready to drop into your stack.
• React dashboard — manage tenants, collections, and documents visually. Search with a query builder.
• Docker Compose deployment — Postgres + pgvector, API server, and dashboard in one command.
• MIT licensed — use it however you want.

⁠Quick Start

cd docker
docker compose up

API at http://localhost:8600, dashboard at http://localhost:8601.

⁠Default Credentials

⁠Store a Document

curl -X PUT http://localhost:8600/v1.0/tenants/ten_default/collections/col_default/documents \
  -H "Authorization: Bearer recalldbadmin" \
  -H "Content-Type: application/json" \
  -d '{
    "DocumentId": "readme-guide",
    "Position": 0,
    "ContentType": "Text",
    "Content": "RecallDB stores embeddings alongside rich metadata.",
    "Embeddings": [0.1, 0.2, 0.3],
    "Labels": ["documentation", "guide"],
    "Tags": [
      { "Key": "source", "Value": "readme" },
      { "Key": "version", "Value": "1.0" }
    ]
  }'

⁠Search

curl -X POST http://localhost:8600/v1.0/tenants/ten_default/collections/col_default/search \
  -H "Authorization: Bearer recalldbadmin" \
  -H "Content-Type: application/json" \
  -d '{
    "Vector": {
      "SearchType": "CosineSimilarity",
      "Embeddings": [0.1, 0.2, 0.3],
      "MinimumScore": 0.7
    },
    "LabelFilter": {
      "Required": ["documentation"]
    },
    "Terms": {
      "Required": ["metadata"]
    },
    "MaxResults": 10
  }'

⁠Search

RecallDB search goes well beyond nearest-neighbor. A single query can combine any of these filters:

Vector — similarity or distance search across 5 metrics with score/distance thresholds.

Labels — require or exclude categorical labels with boolean logic.

Tags — filter on key-value metadata using Equals, NotEquals, GreaterThan, LessThan, Contains, ContainsNot, StartsWith, EndsWith, IsNull, IsNotNull.

Terms — case-insensitive substring matching on document content. Require terms, exclude terms, or both.

Date ranges — CreatedBefore and CreatedAfter for temporal scoping.

Pagination — MaxResults (1-1000) with continuation tokens for large result sets.

Sort — by score, distance, or creation date in ascending or descending order.

⁠SDKs

⁠C#

var client = new RecallDbClient("http://localhost:8600", "recalldbadmin");
var results = await client.SearchAsync("ten_default", "col_default", new SearchQuery
{
    Vector = new VectorQuery
    {
        SearchType = SearchTypeEnum.CosineSimilarity,
        Embeddings = new List<float> { 0.1f, 0.2f, 0.3f },
        MinimumScore = 0.7
    },
    MaxResults = 10
});

⁠Python

from recalldb_sdk import RecallDbClient

client = RecallDbClient("http://localhost:8600", "recalldbadmin")
results = client.search("ten_default", "col_default", {
    "Vector": {
        "SearchType": "CosineSimilarity",
        "Embeddings": [0.1, 0.2, 0.3],
        "MinimumScore": 0.7
    },
    "MaxResults": 10
})

⁠JavaScript

import { RecallDbClient } from 'recalldb-sdk';

const client = new RecallDbClient('http://localhost:8600', 'recalldbadmin');
const results = await client.search('ten_default', 'col_default', {
  Vector: {
    SearchType: 'CosineSimilarity',
    Embeddings: [0.1, 0.2, 0.3],
    MinimumScore: 0.7,
  },
  MaxResults: 10,
});

⁠Configuration

Server settings live in recalldb.json. Environment variables override database connection settings:

⁠Architecture

┌─────────────┐      ┌─────────────────┐      ┌──────────────────────────┐
│  Your App   │────> |  RecallDB API   │────> │  PostgreSQL + pgvector   │
│  (SDK)      │      │  (REST, Auth)   │      │                          │
└─────────────┘      └─────────────────┘      │  tenants                 │
                     ┌─────────────────┐      │  users / credentials     │
                     │   Dashboard     │────> │  collections             │
                     │   (React SPA)   │      │  collection_{id}  [HNSW] │
                     └─────────────────┘      │  collection_{id}_labels  │
                                              │  collection_{id}_tags    │
                                              └──────────────────────────┘

Each collection creates its own Postgres tables with a dedicated HNSW vector index. Labels and tags are stored in separate relational tables and joined at query time, keeping the vector index lean and the metadata queryable.

⁠Building from Source

dotnet restore src/RecallDb.sln
dotnet build src/RecallDb.sln

⁠API Reference

See REST_API.md⁠ for the complete endpoint reference and request/response examples.

A Postman collection⁠ is included for interactive exploration.

⁠License

MIT — see LICENSE.md⁠.