CortexDB

Introduction

CortexDB is an agent-native embedded database for TypeScript applications. It combines durable local storage, memory records, vector search, BM25 full-text search, graph relationships, temporal queries, context packing, agent run tracing, task/goal/plan state, facts, provenance, security scanning, retrieval evaluation, plugins, and a CLI in one local-first library.

The monorepo contains two packages:

• cortexdb — the core embedded database library and CLI.
• @cortexdb/openai — an optional OpenAI-compatible embedding adapter.

CortexDB is ESM-first, pure TypeScript, and requires Node.js 22 or newer.

Installation

Install the core package with your package manager:

pnpm add cortexdb

For OpenAI-compatible embeddings, install the optional adapter too:

pnpm add cortexdb @cortexdb/openai

When working in this repository, install workspace dependencies and build the core package:

pnpm install
pnpm --filter cortexdb build

Quick Start

import { Cortex } from "cortexdb"

const db = await Cortex.memory({
  metadata: { namespace: "quickstart", agentId: "docs-agent" },
})

try {
  const memory = await db.remember({
    content: "CortexDB stores durable agent memories and retrieves them later.",
    kind: "semantic",
    tags: ["quickstart", "memory"],
    trust: "trusted",
    visibility: "private",
  })

  const results = await db.recall({ query: "agent memory retrieval", topK: 3 })
  const packed = await db.context.pack({ records: results, budget: 500 })

  console.log(memory.id)
  console.log(results[0]?.content)
  console.log(db.context.render(packed, { format: "markdown" }))
} finally {
  await db.close()
}

For persistent file-backed storage, open a database directory instead of using memory storage:

import { Cortex } from "cortexdb"

const db = await Cortex.open("./.cortexdb")
await db.remember({ content: "This memory survives process restarts." })
await db.flush()
await db.close()

The CLI uses the same file-backed storage engine:

cortex init ./.cortexdb
cortex --db ./.cortexdb remember "Remember the release checklist" --tag release
cortex --db ./.cortexdb recall release --json
cortex --db ./.cortexdb context pack release --format markdown

API

The main entry point is Cortex:

• Cortex.memory(options?) creates an isolated in-memory database.
• Cortex.open(path, options?) opens a durable file-backed database directory.
• The database handle exposes high-level facades: db.remember(), db.recall(), db.context.pack(), db.search.hybrid(), db.graph.*, db.time.*, db.runs.*, db.tasks.*, db.facts.*, db.security.*, db.plugins.*, db.query.*, and db.transactions.*.

See docs/api-reference.md for signatures and examples for every public API area.

Configuration

Most applications can pass options directly to Cortex.memory() or Cortex.open():

import { Cortex, HashEmbeddingAdapter } from "cortexdb"

const db = await Cortex.memory({
  metadata: { namespace: "tenant-a", agentId: "planner-agent" },
  namespaceIsolation: true,
  embeddingAdapter: new HashEmbeddingAdapter({ dimensions: 128 }),
  context: { defaultBudget: 2000 },
  security: { redactionMarker: "[MASKED]" },
})

Configuration files are supported through defineCortexConfig(), loadCortexConfig(), resolveCortexConfig(), and cortexConfigToOptions(). See docs/configuration.md for config file names, defaults, environment variables, and runtime options.

Documentation

• Getting Started
• Architecture
• API Reference
• Configuration
• Storage Engines
• Security Model
• Plugin Development
• Multi-Agent Usage
• Retrieval Evaluation
• CLI Reference

Development

Repository validation commands are defined in the mission service manifest and package scripts:

pnpm --filter cortexdb test
pnpm --filter cortexdb typecheck
pnpm --filter cortexdb lint
pnpm --filter cortexdb build