Topics — named nodes such as TypeScript, programming language, 2025, or I
Facts — statements that connect multiple topics
Fact-topic links — the relationships that turn one fact into a bridge between many topics

A single fact like I have worked with TypeScript since 2025. can connect the topics I, TypeScript, and 2025 at the same time.

Current foundation capabilities

SQLite, PostgreSQL, MySQL, and MariaDB connection adapters
Automatic schema initialization for topics, facts, and fact_topics
High-level APIs for adding topics and facts
Query APIs for listing topics, loading topic-scoped facts, and finding connected facts/topics
Pluggable fact extraction so callers can use a small LLM or a deterministic extractor

Install

bun install

Quick start

import { IdentityDB, NaiveExtractor } from 'identitydb';

const db = await IdentityDB.connect({
  client: 'sqlite',
  filename: ':memory:',
});

await db.initialize();

await db.ingestStatement('I have worked with TypeScript since 2025.', {
  extractor: new NaiveExtractor(),
});

await db.addFact({
  statement: 'TypeScript is a programming language.',
  topics: [
    {
      name: 'TypeScript',
      category: 'entity',
      granularity: 'concrete',
    },
    {
      name: 'programming language',
      category: 'concept',
      granularity: 'abstract',
    },
  ],
});

const topic = await db.getTopicByName('TypeScript', { includeFacts: true });
const connected = await db.findConnectedTopics('TypeScript');

console.log(topic?.facts.map((fact) => fact.statement));
console.log(connected.map((entry) => [entry.name, entry.sharedFactCount]));

await db.close();

Development

bun run test
bun run check
bun run build

Current status

This repository is in active foundation development.

See docs/plans/2026-05-11-identitydb-foundation.md for the current implementation plan.