# IdentityDB

IdentityDB is a TypeScript package for building structured AI memory on top of relational databases.

## What it is

IdentityDB stores memory as a graph made of:

- **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

```bash
bun install
```

## Quick start

```ts
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

```bash
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.