Quick Start

Get LimbicDB running in under 5 minutes. Zero configuration required.

Installation

npm install limbicdb

That's it. No API keys, no external services, no database setup.

Your First Memory in 30 Seconds

import { open } from 'limbicdb';

// Open a persistent memory store
const db = open('./my-agent.limbic');
await db.init();

// Store memories
await db.remember('User prefers dark mode');
await db.remember('Project deadline is March 15th');
await db.remember('User is allergic to peanuts');

// Semantic recall — finds related memories even with different wording
const result = await db.recall('UI theme preference');
console.log(result.memories[0].content);
// → "User prefers dark mode"

// Keyword recall — exact text matching
const exact = await db.recall('deadline', { mode: 'keyword' });

await db.close();

TIP

Semantic search works out of the box. LimbicDB includes a built-in local embedding model (Xenova/all-MiniLM-L6-v2) that runs entirely on your machine. The ~30MB model is downloaded automatically on first use and cached locally. No API keys needed.

Memory Scopes & Tags

Organize memories with scopes and tags:

await db.remember('Prefers TypeScript over JavaScript', {
  scope: 'core',          // core | project | session | archive
  tags: ['preference', 'programming'],
  projectId: 'limbicdb',
});

// Filter by scope and tags
const prefs = await db.recall('programming preferences', {
  scope: 'core',
  tags: ['preference'],
});

Sessions

Track conversation context across sessions:

// Create a session
const session = await db.createSession({
  name: 'Code review chat',
  projectId: 'limbicdb',
});

// Remember within a session
await db.remember('User asked about performance optimization', {
  sessionId: session.id,
});

// Recall only from this session
const sessionMemories = await db.recall('optimization', {
  sessionId: session.id,
});

Using a Custom Embedder

While the built-in embedder works great for most cases, you can plug in any embedding provider:

// OpenAI example
import { open } from 'limbicdb';

const db = open({
  path: './agent.limbic',
  embedder: {
    dimensions: 1536,
    modelHint: 'text-embedding-3-small',
    embed: async (text) => {
      const res = await fetch('https://api.openai.com/v1/embeddings', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.OPENAI_API_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ input: text, model: 'text-embedding-3-small' }),
      });
      const data = await res.json();
      return data.data[0].embedding;
    },
  },
});

To explicitly disable semantic search (keyword-only mode):

const db = open({ path: './agent.limbic', embedder: false });

Memory Graph

LimbicDB automatically builds a cognitive memory graph — linking related memories:

import { open, findRelated, getContextGraph } from 'limbicdb';

const db = open('./agent.limbic');
await db.init();

// After storing several memories, find related ones
const related = await findRelated(db, 'some-memory-id', { maxDepth: 2 });

// Get the full context graph around a memory
const graph = await getContextGraph(db, 'some-memory-id');
console.log(graph.nodes, graph.edges);

await db.close();

Encryption

Encrypt all memory content at rest with a single passphrase:

const db = open({
  path: './secure-agent.limbic',
  vaultPassphrase: 'my-secret-passphrase',
});
await db.init();

// All memories are now AES-256-GCM encrypted on disk
await db.remember('SSN: 123-45-6789');

What's Next?

• Architecture Guide — How LimbicDB works under the hood
• Integration Guide — LangChain, LlamaIndex, MCP Server
• Security Guide — Encryption, sync security, access control
• Benchmarks — Performance characteristics