cortexdb

package module
v2.62.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 31, 2026 License: MIT Imports: 0 Imported by: 0

README

CortexDB

Go Reference CI codecov

A pure-Go, single-file AI memory and knowledge graph library and plugin. Use CortexDB as an embedded memory/KG layer in your own Go agent projects, or install it as a shared memory brain for Claude Code and Codex. SQLite is the kernel — one file holds vectors, lexical/RAG search, scoped agent memory, an RDF/SPARQL/RDFS/SHACL knowledge graph, and MCP tools. Works with no embedder (lexical mode) or any OpenAI-compatible embeddings endpoint.

Why CortexDB?

Use CortexDB when you want an agent memory layer that is embedded, inspectable, and graph-aware without standing up more infrastructure.

If you were considering... CortexDB gives you... Trade-off
chromem-go or a small embedded vector store Vectors plus lexical search, durable knowledge, scoped memory, RDF/SPARQL, and MCP tools in one SQLite file More surface area if all you need is a tiny vector collection
sqlite-vec or raw SQLite extensions A Go facade for RAG, memory, hybrid retrieval, graph facts, and agent tools Less low-level SQL control than wiring extensions yourself
Chroma, Qdrant, LanceDB, or a hosted vector DB No service to run, no separate storage plane, and lexical mode with no API key Not trying to be a distributed vector database
Fuseki, GraphDB, Stardog, or a standalone graph DB Enough RDF/SPARQL/RDFS/SHACL for local-first agent workflows, next to the text and memory store Not a full enterprise RDF server
Custom memory tables for Claude Code/Codex A packaged plugin, MCP server, auto-recall path, and reusable memory/KG tools Bring your own product-specific memory policy

Planning a launch or community post? See docs/LAUNCH_KIT.md for ready-to-edit Show HN, Reddit, and demo scripts.

Install & Quick Start

go get github.com/liliang-cn/cortexdb/v2

db, _ := cortexdb.Open(cortexdb.DefaultConfig("KnowledgeMemory.db"))
defer db.Close()

q := db.Quick()
_, _ = q.Add(ctx, []float32{0.1, 0.2, 0.9}, "SQLite is a single-file database.")
hits, _ := q.Search(ctx, []float32{0.1, 0.2, 0.8}, 1)

// No-embedder RAG (lexical):
_, _ = db.SaveKnowledge(ctx, cortexdb.KnowledgeSaveRequest{
    KnowledgeID: "apollo", Content: "Alice owns Apollo. Apollo ships Friday."})
resp, _ := db.SearchKnowledge(ctx, cortexdb.KnowledgeSearchRequest{
    Query: "Who owns Apollo?", RetrievalMode: cortexdb.RetrievalModeLexical, TopK: 3})

Layers — pick the right one

pkg/cortexdb   Main facade: vectors, text/RAG search, knowledge, memory, KG, tools, MCP.  ← start here
pkg/memoryflow Agent memory workflow: transcript ingest, recall, wake-up layers, promotion.
pkg/graphflow  Corpus → extract → build → analyze → report → export (HTML).
pkg/importflow Import CSV / SQL dumps / live Postgres-MySQL into RAG + KG (DDL → graph).
pkg/connector  Privacy gate over importflow: PII masking, signed plan, reversible vault, CDC sync.
pkg/graph      Low-level RDF/SPARQL/RDFS/SHACL + property graph.
pkg/core       SQLite storage, embeddings, FTS5, vector indexes (HNSW/IVF/Flat).

Knowledge Graph

Embedded RDF on the same file: triples/quads, namespaces, N-Triples/Turtle/TriG I/O, a practical SPARQL subset (SELECT/ASK/CONSTRUCT/DESCRIBE, updates, OPTIONAL/UNION/MINUS/VALUES/BIND/FILTER, aggregates, subqueries, property paths ^p p|q p+ p*), RDFS-lite materialized inference, and SHACL-lite validation.

db.UpsertKnowledgeGraph(ctx, cortexdb.KnowledgeGraphUpsertRequest{Triples: triples})
res, _ := db.QueryKnowledgeGraph(ctx, cortexdb.KnowledgeGraphQueryRequest{
    Query: `SELECT ?name WHERE { <https://example.com/alice> <https://schema.org/name> ?name }`})

Tools, MCP & Plugin

tools := db.GraphRAGTools()                             // in-process tool calling
server := db.NewMCPServer(cortexdb.MCPServerOptions{})  // MCP server

Tool groups: GraphRAG (ingest_document, search_text, build_context), knowledge/memory (knowledge_save, memory_search, …), KG (knowledge_graph_query, _shacl_validate), KnowledgeMemory (knowledge_memory_recall, _reflect). memoryflow/graphflow/importflow/connector expose their own toolboxes too.

Claude Code and Codex plugin

Give Claude Code (and Codex) durable memory + a knowledge graph as a plugin. It bundles the cortexdb skill plus a live MCP server, runs in no-embedder lexical mode by default (no API key, no Go toolchain — the server binary is fetched from the matching release), and stores everything in one global SQLite file shared by every project.

Install — Claude Code — run each as a slash command:

/plugin marketplace add liliang-cn/cortexdb
/plugin install cortexdb@cortexdb
/reload-plugins

Install — Codex — run in your shell:

codex plugin marketplace add liliang-cn/cortexdb
codex plugin add cortexdb@cortexdb

Codex uses the same default global brain at ~/.cortexdb/cortexdb.db.

Use — just talk to Claude; it calls the MCP tools for you ("remember that I prefer …", "what do you know about X?"). Or use the slash commands: /remember <text>, /recall <query>, /cortexdb-graph (interactive knowledge-graph view), or /cortexdb for the skill. Key tools: memory_save / memory_search, knowledge_save / knowledge_search, knowledge_graph_query, and the unified knowledge_memory_recall. When enabled, a SessionStart directive + UserPromptSubmit auto-recall hook make Claude recall and save proactively (it asks once, per machine).

Where data lives — ~/.cortexdb/cortexdb.db by default, so memory follows you across projects (multiple sessions share it safely via SQLite WAL). Override per project:

export CORTEXDB_PATH=.cortexdb/cortexdb.db   # inherited by the launched server

To force the same global brain explicitly, set:

export CORTEXDB_PATH="$HOME/.cortexdb/cortexdb.db"

To upgrade: /plugin update cortexdb then /reload-plugins — the server binary auto-refreshes (version-pinned cache). See plugins/cortexdb/README.md for all env vars.

OpenClaw and Hermes memory plugins

CortexDB also ships native memory-layer adapters for agents that expose a memory lifecycle API. Both use the existing gRPC sidecar and unified knowledge_memory_recall; they do not add a parallel storage path.

# OpenClaw
openclaw plugins install npm:cortexdb-openclaw-memory@2.57.1
openclaw config set plugins.slots.memory cortexdb-memory
openclaw gateway restart

# Hermes Agent
hermes plugins install liliang-cn/hermes-cortexdb-memory --enable
hermes config set memory.provider cortexdb
hermes gateway restart

Run cortexdb-grpc, then install the adapter. The existing skills/ remain useful for explicit tool instructions and helper functions, but a skill alone does not replace the host agent's native memory backend.

Other languages (gRPC sidecar)

cortexdb-grpc serves the full facade over gRPC, with typed clients for Rust/Python/Node:

go install github.com/liliang-cn/cortexdb/v2/cmd/cortexdb-grpc@latest
CORTEXDB_PATH=my.db CORTEXDB_GRPC_TOKEN=s3cret cortexdb-grpc   # 127.0.0.1:47821
cargo add cortexdb-client   # pip install cortexdb-client   # npm install cortexdb-client

Quality

Retrieval quality is measured, not assumed: pkg/eval runs a labeled query set through the real retrieval path and reports recall@k / precision@k / MRR / nDCG, with regression floors in CI (go test ./pkg/eval -run TestLexicalRetrievalQuality -v). Parser/search surfaces (FTS5, SPARQL, SQL-dump import) have Go fuzz tests (go test ./... -run Fuzz); their saved corpora are permanent regression seeds.

Examples & Status

examples/01_core … 15_cortex_query are small and architecture-oriented (go run ./examples/01_core); 01-07/09/15 run standalone, others need an LLM/embeddings/live DB — see examples/README.md.

An embedded local-first AI memory/KG library — not a drop-in replacement for Fuseki/GraphDB/Stardog. One file, Go APIs, tool/MCP surfaces, and enough RDF/SPARQL/RDFS/SHACL to build real memory workflows.

Documentation

Overview

Package cortexdb is the public documentation entrypoint for CortexDB.

CortexDB is a pure-Go, single-file AI memory and knowledge graph library. It uses SQLite as the storage kernel and exposes vector search, lexical search, RAG knowledge storage, scoped agent memory, RDF/SPARQL/RDFS/SHACL knowledge graph features, corpus-to-graph workflows, and MCP-aligned tool APIs.

Architecture

The main packages are:

  • pkg/cortexdb: primary DB facade for vectors, text search, knowledge, memory, KnowledgeMemory recall, knowledge graph APIs, GraphRAG tools, and MCP.
  • pkg/memoryflow: agent memory workflow for transcript ingest, recall, wake-up layers, diary, transcript reconstruction, and promotion.
  • pkg/graphflow: corpus-to-graph workflow for extraction schema, build, analysis, report, JSON/Markdown/HTML export, and optional LLM extraction.
  • pkg/graph: low-level graph engine for property graph operations, RDF triples/quads, SPARQL, RDFS-lite inference, and SHACL-lite validation.
  • pkg/core: low-level SQLite storage, embeddings, FTS5, indexes, and chat/session primitives.

Use pkg/cortexdb first unless you need a workflow layer or low-level graph control.

Quick Start 

import (
	"context"
	"github.com/liliang-cn/cortexdb/v2/pkg/cortexdb"
)

func main() {
	db, _ := cortexdb.Open(cortexdb.DefaultConfig("KnowledgeMemory.db"))
	defer db.Close()

	ctx := context.Background()
	quick := db.Quick()

	_, _ = quick.Add(ctx, []float32{0.1, 0.2, 0.9}, "SQLite is a single-file database.")
	_, _ = quick.Search(ctx, []float32{0.1, 0.2, 0.8}, 3)
}

Knowledge and Memory

Durable knowledge and scoped memory are available directly on DB: 

_, _ = db.SaveKnowledge(ctx, cortexdb.KnowledgeSaveRequest{
	KnowledgeID: "apollo-plan",
	Title:       "Apollo launch plan",
	Content:     "Alice owns Apollo. Apollo ships on Friday.",
	Keywords:    nil,
})

_, _ = db.SearchKnowledge(ctx, cortexdb.KnowledgeSearchRequest{
	Query:         "Who owns Apollo?",
	Keywords:      []string{"Apollo", "Alice", "owns"},
	RetrievalMode: cortexdb.RetrievalModeLexical,
	TopK:          3,
})

_, _ = db.SaveMemory(ctx, cortexdb.MemorySaveRequest{
	MemoryID:  "style",
	UserID:    "user-1",
	Scope:     cortexdb.MemoryScopeUser,
	Namespace: "assistant",
	Content:   "User prefers concise status updates.",
})

Knowledge Graph

The high-level knowledge graph API supports RDF triples/quads, import/export, SPARQL, RDFS-lite inference, and SHACL-lite validation: 

_, _ = db.UpsertKnowledgeGraph(ctx, cortexdb.KnowledgeGraphUpsertRequest{
	Triples: []cortexdb.KnowledgeGraphTriple{
		{
			Subject:   graph.NewIRI("https://example.com/alice"),
			Predicate: graph.NewIRI(graph.RDFType),
			Object:    graph.NewIRI("https://example.com/Person"),
		},
	},
})

_, _ = db.QueryKnowledgeGraph(ctx, cortexdb.KnowledgeGraphQueryRequest{
	Query: `SELECT ?o WHERE { <https://example.com/alice> ?p ?o . }`,
})

_, _ = db.RefreshKnowledgeGraphInference(ctx, cortexdb.KnowledgeGraphInferenceRefreshRequest{
	Mode: cortexdb.KnowledgeGraphInferenceRefreshModeIncremental,
})

SPARQL support is a practical embedded subset. It includes SELECT, ASK, CONSTRUCT, DESCRIBE, update forms, OPTIONAL, UNION, MINUS, VALUES, BIND, FILTER, EXISTS, NOT EXISTS, aggregates, subqueries, and constrained property paths such as ^pred, p|q, p+, and p*.

MemoryFlow

Use pkg/memoryflow for chat/session memory workflows: 

flow, _ := memoryflow.New(db, planner, extractor)
_, _ = flow.IngestTranscript(ctx, memoryflow.IngestTranscriptRequest{...})
_, _ = flow.WakeUpLayers(ctx, memoryflow.WakeUpLayersRequest{...})

Hindsight can be used as an optional recall strategy plugin without replacing memoryflow: 

flow, _ := memoryflow.New(
	db,
	planner,
	extractor,
	memoryflow.WithRecallStrategy(hindsight.NewStrategy(db, hindsight.StrategyOptions{
		BankID:      "apollo-agent",
		EntityNames: []string{"Apollo"},
		Keywords:    []string{"deadline"},
		UseKG:       true,
	})),
)

LLM-dependent parts are interfaces: QueryPlanner, SessionExtractor, and PromotionPolicy.

GraphFlow

Use pkg/graphflow for corpus-to-graph workflows: 

// ExtractionResult can come from deterministic code or an LLM.
_, _ = graphflow.Build(ctx, db, []graphflow.ExtractionResult{extraction}, graphflow.BuildOptions{})
report, _ := graphflow.Analyze(ctx, db, graphflow.AnalyzeRequest{TopN: 10})
_, _ = graphflow.Export(ctx, db, graphflow.ExportRequest{OutputDir: "graphflow-out", Analysis: report})

LLM extraction depends only on graphflow.JSONGenerator. The example examples/05_graphflow demonstrates github.com/openai/openai-go/v3 with JSON Schema structured output.

Tools and MCP

In-process tool calling: 

tools := db.GraphRAGTools()
defs := tools.Definitions()
resp, err := tools.Call(ctx, "knowledge_graph_query", payload)
_, _, _ = defs, resp, err

MCP: 

server := db.NewMCPServer(cortexdb.MCPServerOptions{})
_ = server

Examples

The examples directory is organized by architecture: 

go run ./examples/01_core
go run ./examples/02_rag
go run ./examples/03_memoryflow
go run ./examples/04_knowledge_graph
go run ./examples/05_graphflow
go run ./examples/06_tools_mcp

Index

Constants

View Source 
const Version = "2.62.1"

Version represents the current version of the cortexdb library.

Variables

This section is empty.

Functions

This section is empty.

Types

This section is empty.

Source Files

View all Source files

Directories

Path Synopsis
cmd
cortexdb-connector-mcp command
cortexdb-connector-mcp runs the data-connector tools (connector_introspect, connector_plan, connector_run, connector_unmask) as an MCP stdio server.
 cortexdb-connector-mcp runs the data-connector tools (connector_introspect, connector_plan, connector_run, connector_unmask) as an MCP stdio server.
cortexdb-grpc command
Command cortexdb-grpc serves the pkg/cortexdb facade over gRPC.
 Command cortexdb-grpc serves the pkg/cortexdb facade over gRPC.
cortexdb-mcp-stdio command
examples
01_core command
02_rag command
03_memoryflow command
04_knowledge_graph command
05_graphflow command
06_tools_mcp command
07_importflow command
08_self_knowledge_graph command
Dogfooding demo: turn docs/PROJECT_OVERVIEW.md (CortexDB's own project overview) into a knowledge graph using CortexDB's graphflow workflow, with an LLM extractor.
 Dogfooding demo: turn docs/PROJECT_OVERVIEW.md (CortexDB's own project overview) into a knowledge graph using CortexDB's graphflow workflow, with an LLM extractor.
09_connector command
Demo: desensitize a CSV through the connector privacy gate, then import to RAG.
 Demo: desensitize a CSV through the connector privacy gate, then import to RAG.
10_support_brain command
Customer-support "agent brain" — an end-to-end CortexDB demo over a REAL database (Postgres or MySQL).
 Customer-support "agent brain" — an end-to-end CortexDB demo over a REAL database (Postgres or MySQL).
11_unified_brain command
Unified support brain — a complex, multi-source CortexDB application.
 Unified support brain — a complex, multi-source CortexDB application.
12_incident_agent command
Incident-analysis agent — a complex CortexDB example that REQUIRES an LLM (a chat/generation model, not an embedding model).
 Incident-analysis agent — a complex CortexDB example that REQUIRES an LLM (a chat/generation model, not an embedding model).
13_scale_analytics command
Scale + analytics — a comprehensive, larger-volume CortexDB example.
 Scale + analytics — a comprehensive, larger-volume CortexDB example.
14_semantic_rag command
Semantic RAG — CortexDB with a real embedding model (vector search), plus an LLM answer.
 Semantic RAG — CortexDB with a real embedding model (vector search), plus an LLM answer.
15_cortex_query command
Cortex Query — composable retrieval over one local CortexDB file.
 Cortex Query — composable retrieval over one local CortexDB file.
kg_e2e command
Command kg_e2e is a runnable, fully-printed end-to-end walkthrough of the CortexDB RDF / Knowledge Graph stack through the public pkg/cortexdb facade.
 Command kg_e2e is a runnable, fully-printed end-to-end walkthrough of the CortexDB RDF / Knowledge Graph stack through the public pkg/cortexdb facade.
internal
encoding
pkg
agentmem
Package agentmem is a SQL-backed agent memory store.
 Package agentmem is a SQL-backed agent memory store.
connector
Package connector turns live data sources into agent-usable knowledge with desensitization as a first-class step.
 Package connector turns live data sources into agent-usable knowledge with desensitization as a first-class step.
core
Package core provides advanced search capabilities
 Package core provides advanced search capabilities
cortexdb
Package cortexdb provides a lightweight SQLite-based vector database for Go AI projects
 Package cortexdb provides a lightweight SQLite-based vector database for Go AI projects
eval
Package eval is a retrieval-quality evaluation harness for CortexDB.
 Package eval is a retrieval-quality evaluation harness for CortexDB.
geo
Package geo provides geo-spatial indexing and search capabilities for cortexdb
 Package geo provides geo-spatial indexing and search capabilities for cortexdb
graph
graphflow
Package graphflow provides a library-first graph extraction/build/report/export pipeline over CortexDB's graph and RDF storage.
 Package graphflow provides a library-first graph extraction/build/report/export pipeline over CortexDB's graph and RDF storage.
hindsight
Package hindsight: chat.go provides a thin wrapper around the cortexdb session/message API that optionally auto-triggers fact extraction.
 Package hindsight: chat.go provides a thin wrapper around the cortexdb session/message API that optionally auto-triggers fact extraction.
importflow
Package importflow imports external structured data (CSV, MySQL/PG SQL dumps) into CortexDB, building RAG (vector/FTS5) and knowledge-graph (RDF triple) foundations in a single pass.
 Package importflow imports external structured data (CSV, MySQL/PG SQL dumps) into CortexDB, building RAG (vector/FTS5) and knowledge-graph (RDF triple) foundations in a single pass.
index
Package index provides vector indexing implementations
 Package index provides vector indexing implementations
memoryflow
Package memoryflow provides a higher-level workflow facade on top of CortexDB's memory, knowledge, and KnowledgeMemory primitives.
 Package memoryflow provides a higher-level workflow facade on top of CortexDB's memory, knowledge, and KnowledgeMemory primitives.
quantization
Package quantization provides vector compression techniques
 Package quantization provides vector compression techniques
rpc/v1
rpcserver
Package rpcserver exposes the pkg/cortexdb facade over gRPC.
 Package rpcserver exposes the pkg/cortexdb facade over gRPC.
semantic-router
Package semantic-router provides a semantic routing layer for LLM applications.
 Package semantic-router provides a semantic routing layer for LLM applications.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.