83 lines
2.1 KiB
Markdown
83 lines
2.1 KiB
Markdown
# 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.
|