CognitiveDB TypeScript SDK

TypeScript client for CognitiveDB - Smart memory database for AI agents.

Installation

npm install cognitivedb
# or
yarn add cognitivedb
# or
pnpm add cognitivedb

Quick Start

import { CognitiveDB } from 'cognitivedb';

// Create client
const db = new CognitiveDB({
  baseUrl: 'http://localhost:6969',
  defaultCollection: 'my-app'
});

// Ingest content with cognitive processing
const result = await db.ingest('User prefers dark mode and TypeScript');
console.log('Extracted facts:', result.facts);
console.log('Extracted concepts:', result.concepts);

// Recall relevant memories
const memories = await db.recall('What are the user preferences?');
for (const { memory, cognitive_score } of memories.results) {
  console.log(`[${cognitive_score.toFixed(2)}] ${memory.content}`);
}

API Reference

Constructor

const db = new CognitiveDB({
  baseUrl?: string;          // Default: 'http://localhost:6969'
  defaultCollection?: string; // Default: 'default'
  timeout?: number;          // Default: 30000 (ms)
  headers?: Record<string, string>;
});

Methods

ingest(content, options?)

Ingest content with full cognitive processing (embeddings, fact extraction, concept extraction).

const result = await db.ingest('I prefer TypeScript', {
  collection: 'preferences',
  metadata: { source: 'chat' }
});
// Returns: { memory_ids, facts, concepts }

recall(query, options?)

Recall memories using hybrid cognitive search.

const result = await db.recall('user preferences', {
  limit: 10,
  weights: {
    similarity: 0.5,  // Vector similarity weight
    recency: 0.3,     // Temporal recency weight
    salience: 0.2     // Importance weight
  }
});
// Returns: { results: MemoryResult[] }

store(content, options?)

Store a memory without cognitive processing (raw mode).

const { id } = await db.store('Important fact', {
  memoryType: 'Fact',
  metadata: { importance: 'high' }
});

get(id, collection?)

Get a specific memory by ID.

const memory = await db.get('uuid-here');

delete(id, collection?)

Delete a memory by ID.

await db.delete('uuid-here');

decay(rate?, collection?)

Apply salience decay to memories.

const { affected_count } = await db.decay(0.1);

consolidate(threshold?, collection?)

Consolidate similar memories using LLM.

const { consolidated_count } = await db.consolidate(0.8);

reflect(windowSize?, collection?)

Generate insights from recent memories.

const { reflection } = await db.reflect(10);

stats(collection?)

Get collection statistics.

const stats = await db.stats();
// { memory_count, fact_count, concept_count, relation_count, vector_count }

purge(collection?)

Delete all memories in a collection.

const { deleted_count } = await db.purge();

health()

Check server health.

const { healthy, version } = await db.health();

Error Handling

import { 
  CognitiveDBError,
  MemoryNotFoundError,
  ConnectionError 
} from 'cognitivedb';

try {
  await db.get('non-existent-id');
} catch (error) {
  if (error instanceof MemoryNotFoundError) {
    console.log('Memory not found');
  } else if (error instanceof ConnectionError) {
    console.log('Server unavailable');
  } else if (error instanceof CognitiveDBError) {
    console.log(`Error: ${error.message} (${error.code})`);
  }
}

Types

interface Memory {
  id: string;
  collection: string;
  content: string;
  memory_type: string;
  salience: number;
  timestamp: number;
  metadata?: Record<string, string>;
}

interface MemoryResult {
  memory: Memory;
  similarity: number;
  recency: number;
  salience: number;
  cognitive_score: number;
}

type MemoryType = 'Conversation' | 'Fact' | 'Insight' | 'Summary';

License

MIT