/cortexdb

name: cortexdb
description: Use CortexDB for local-first AI memory, vector search, RAG, knowledge graphs, SPARQL/RDFS/SHACL, corpus-to-graph workflows, and MCP/tool calling. Use when working with CortexDB, embeddings, memory, RAG, GraphRAG, knowledge graph, RDF, SPARQL, SHACL, memoryflow, graphflow, or MCP tools.

CortexDB Skill

CortexDB is a pure-Go, single-file AI memory and knowledge graph library built on SQLite.

Current Architecture

Use the right layer:

pkg/cortexdb
  Main public DB facade: vectors, text search, knowledge, memory, KnowledgeMemory, KG, tools, MCP.

pkg/memoryflow
  Agent memory workflow: transcript ingest, recall, wake-up layers, diary, promotion.

pkg/graphflow
  Corpus-to-graph workflow: extraction schema, build, analyze, report, export, HTML.

pkg/importflow
  Structured-data import workflow: CSV / live Postgres / live MySQL -> RAG + knowledge graph.

pkg/connector
  Privacy gate in front of importflow: live-source introspection, PII classification,
  human-signed MaskingPlan, desensitization (masking + free-text redaction + reversible
  per-tenant AES-256-GCM token vault). Feeds RAG + KG; agent tools + MCP server.

pkg/graph
  Low-level graph engine: property graph, RDF triples/quads, SPARQL, RDFS, SHACL.

pkg/core
  SQLite storage, embeddings, FTS5, vector indexes, chat/session primitives.

Default recommendation:

• Use `pkg/cortexdb` for application code.
• Use `pkg/memoryflow` for chat/session/agent memory workflows.
• Use `pkg/graphflow` for document/corpus-to-graph extraction and report/export workflows.
• Use `pkg/importflow` to import structured data (CSV / live Postgres / MySQL) into RAG + KG.
• Use `pkg/connector` when that structured data contains PII and must be desensitized

(under a human-signed plan) before it enters RAG/KG, with reversible un-mask via a vault.

• Use `pkg/graph` only for low-level RDF/SPARQL/RDFS/SHACL or property graph control.

Install

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

Core DB Usage

db, err := cortexdb.Open(cortexdb.DefaultConfig("KnowledgeMemory.db"))
if err != nil {
    return err
}
defer db.Close()

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

Small devices

`cortexdb.EmbeddedConfig(path)` is the configuration for a Raspberry Pi, an industrial gateway or a router-class ARM board — Linux with an MMU and a few hundred megabytes. It holds the HNSW index as SQ8 codes, keeps SQLite to a 1 MiB page cache on each of at most 4 connections with up to 64 MiB of the file memory-mapped and temporary b-trees in files, and saves the index snapshot every 10 minutes when it has changed, so a power cut costs at most that much rebuilding. On 100,000 768-d vectors a store opens from its snapshot in 0.28 s with a 193 MB heap and a 297 MB peak RSS. The same settings are fields on `Config` (`Quantization`, `Binary`, `Resources`, `SnapshotInterval`) for a mix of your own. `IndexTypeBinary` is the smallest index — 27.5 MB of heap at 100,000 vectors — but has no snapshot (each open scans the table twice) and needs `Binary.Oversample` raised for tightly clustered vectors. Without an embedder none of the vector settings matter; the SQLite limits are what bound memory. Run with `GOMEMLIMIT` set below the device's memory so the garbage collector works before the kernel does.

Knowledge and Memory

_, _ = db.SaveKnowledge(ctx, cortexdb.KnowledgeSaveRequest{
    KnowledgeID: "apollo-plan",
    Title:       "Apollo launch plan",
    Content:     "Alice owns Apollo. Apollo ships on Friday.",
    ChunkSize:   24,
    Entities: []cortexdb.ToolEntityInput{
        {Name: "Alice", Type: "person", ChunkIDs: []string{"chunk:apollo-plan:000"}},
        {Name: "Apollo", Type: "project", ChunkIDs: []string{"chunk:apollo-plan:000"}},
    },
    Relations: []cortexdb.ToolRelationInput{
        {From: "Alice", To: "Apollo", Type: "owns"},
    },
})

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

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

No-embedder mode is supported. Use lexical retrieval plus LLM-planned `Keywords`, `AlternateQueries`, `EntityNames`, and `RetrievalMode`.

Retrieval mode `ppr` runs Personalized PageRank (HippoRAG 2 style) from the entities a question names, rank-fused with the first stage; tune it with `ppr: {fusion, damping, passage_seed_weight, edge_type_weights}`. Without an embedder, `auto` takes that walk whenever a knowledge search names an entity specific enough to start from (an entity more than 10% of passages mention, like a conversation's speaker, is not) and stays lexical otherwise — recall@5 through the public API, lexical → auto: 2WikiMultiHopQA 0.657 → 0.807, MuSiQue 0.457 → 0.542, LoCoMo 0.493 → 0.495, LongMemEval 0.861 → 0.862. `SaveKnowledge` builds the entity graph without an embedder too, and a title that reads as a name links every chunk of its document. With an embedder `auto` stays hybrid; pass `retrieval_mode: "ppr"` for multi-hop questions.

The live view (`serve_graph_3d`) can be asked, not only looked at: find any node in the store, ask a question and see what the answer names, run read-only Cypher, expand a node's neighbours past the drawn core. It is read-only, works on a phone, has light and dark themes, and opens wherever its link says (`?focus=`, `?ask=`, `?cypher=`, `?find=`, `?type=`, `?edge=`, `?theme=`, `?mode=`). The same server draws the brain as a library (`library_url` in the result, or `view=library`):