liliang-cn/cortexdb

CortexDB – AI‑augmented memory & knowledge graph in a single SQLite file

What it is – CortexDB is a pure‑Go library that lets you store and retrieve “memories” for AI agents. It combines vector‑based similarity search, full‑text search and a standards‑compliant RDF knowledge graph, all persisted in a single SQLite (or PostgreSQL) database. No external service or embedding model is required unless you choose to plug one in.

Why it matters – Modern LLM‑based agents need a place to keep facts, context, and relationships that survive across sessions and even across machines. CortexDB gives them a fast, local, self‑contained brain that can be shared via a lightweight gRPC server, making it easy to build RAG pipelines, scoped agent memory, or a collaborative knowledge base without managing separate vector stores or graph databases.

How to get it

• Go library: go get github.com/liliang-cn/cortexdb/v2
• CLI server (shared‑brain): go install github.com/liliang-cn/cortexdb/v2/cmd/cortexdb-grpc@latest
• Language bindings: cargo add cortexdb-client, pip install cortexdb-client, npm install cortexdb-client
• Plugins for Claude Code, Codex, DeepSeek Harness are also provided.

Basic usage (Go)

db, _ := cortexdb.Open(cortexdb.DefaultConfig("brain.db"))
defer db.Close()
brain := db.KnowledgeMemory()
_, _ = brain.Remember(ctx, cortexdb.KnowledgeMemoryRememberRequest{Content: "Alice prefers tabs.", Scope: "user"})
rec, _ := brain.Recall(ctx, cortexdb.KnowledgeMemoryRecallRequest{Query: "what does Alice prefer?"})
fmt.Println(rec.ContextPack.Text) // → "Alice prefers tabs."

The example shows how to store a fact and later retrieve it with a natural‑language query.

Key capabilities

• Vector indexes – HNSW, IVF, flat, binary codes; hybrid search with FTS5 full‑text.
• RDF 1.2 graph – SPARQL 1.1/1.2, RDFS + OWL 2 RL inference, SHACL validation; also read‑only Cypher support.
• RAG & scoped memory – Memories can be scoped (e.g., per user or session) and returned as “context packs” with source citations.
• Live 3‑D graph viewer – serve_graph_3d visualises the knowledge graph on desktop or phone.
• Change feed – Every write is recorded in order, guaranteeing exactly‑once replay.
• Pluggable embeddings – By default it works in lexical mode; you can point it at any OpenAI‑compatible embeddings endpoint via CORTEXDB_EMBED_BASE_URL.
• Portable storage – SQLite by default; PostgreSQL + pgvector is also supported.
• Shared‑brain server – Run cortexdb-grpc to let multiple agents or machines access the same brain over gRPC, with optional token authentication.

Integration with AI assistants

• Claude Code & Codex plugins expose /remember and /recall commands and automatic‑recall hooks, giving the IDE a global brain stored at ~/.cortexdb/cortexdb.db.
• The optional cortexdb-live mod adds UI features: planned recall previews, status line showing brain health, and automatic capture of conversation snippets into durable memories after a period of inactivity.

Configuration (environment variables)

Variable	Purpose
CORTEXDB_PATH	Path to the local SQLite file (default ~/.cortexdb/cortexdb.db).
CORTEXDB_REMOTE	URL of a remote cortexdb-grpc server to use instead of a local file.
CORTEXDB_GRPC_TOKEN	Bearer token for authenticating to the remote server.
CORTEXDB_EMBED_BASE_URL	Base URL of an OpenAI‑compatible embeddings service; if unset, CortexDB falls back to lexical (keyword) mode.
CORTEXDB_EMBED_MODEL / CORTEXDB_EMBED_DIM	Model name and vector dimension for custom embeddings.
CORTEXDB_SLOW_MS	Threshold (ms) for logging slow server calls.
CORTEXDB_TRACE / CORTEXDB_TRACE_FILE	Enable full request tracing, optionally writing JSON‑lines to a file.

Documentation & community

• Official site: https://liliang-cn.github.io/cortexdb/
• Full feature guide: docs/GUIDE.md
• Example code: examples/README.md
• Change log and Chinese README also provided.

License – MIT, allowing free use, modification, and distribution.

---

In short, CortexDB is a lightweight, embeddable AI memory store that blends vector similarity, full‑text, and RDF graph capabilities into a single, portable database, with ready‑made integrations for popular LLM‑powered development tools.