Cortexdb

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/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/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

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): each memory is a book on the shelf of the project it names, shelves group into wings by their projects' relations, an entity is an index card listing every book that mentions it, and a book opens on a lectern with its text, index and see-also.

import_agent_memory brings in the memory a person already has, so a new brain does not start empty. By default it imports Claude Code's memory notes (~/.claude/projects/*/memory/*.md), CLAUDE.md / AGENTS.md, and Codex's own memories (~/.codex/memories_1.sqlite and the notes in ~/.codex/memories). With sources: ["claude_sessions", "codex_sessions"] it also distils past transcripts into memories, the way a session is captured when it ends. Each transcript is a model call (CORTEXDB_LLM_*), so one call does max_sessions (default 5) and says how many are left; since limits the window (30d, 2026-09-01), and ~/.cortexdb/imported-sessions.json keeps a transcript from being read twice. Like render_graph_html it runs where the MCP server runs, because that is where the files are, and writes to whichever brain the server uses, local or shared. dry_run counts first; ids are stable, so running it again refreshes rather than duplicates. From a shell: cortexdb-mcp --import-agent-memory [--sessions] [--since 30d] [--max N] [--dry-run].

A capture also retires what it made untrue. Each fact a session yields is looked up in the brain, and one more model call is asked which existing memories it contradicts — the same thing with a different current value, not merely the same topic. Those are saved as superseded by the new memory (supersedes): kept, exported, stamped superseded_by / superseded_at, and no longer recalled as current, so a wrong call is undone by clearing one key. The later date wins: a fact from a session imported months late does not retire newer memories, and is dropped if one already contradicts it. At most five memories are retired per pass, and a failed check saves everything and retires nothing. The SessionEnd capture, the cortexdb-live mod and import_agent_memory's session import all do this.

Chinese (and other CJK) questions work in lexical mode as written: a sentence is cut at function words, broken into character bigrams and ranked with BM25 beside the word-index results. A row is returned only when it matches more than one word of the question, so a question the store knows nothing about still returns nothing.

Knowledge Graph APIs

High-level APIs live in pkg/cortexdb:

• UpsertKnowledgeGraph
• FindKnowledgeGraph
• DeleteKnowledgeGraph
• ImportKnowledgeGraph
• ExportKnowledgeGraph
• QueryKnowledgeGraph
• ValidateKnowledgeGraphSHACL
• RefreshKnowledgeGraphInference
• SummarizeKnowledgeGraphInference
• ExplainKnowledgeGraphInference
• ExplainKnowledgeGraphInferenceMatch

_, _ = 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"),
        },
    },
})

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

SPARQL is SPARQL 1.1 and 1.2, measured against the W3C test suites: SELECT (DISTINCT, REDUCED, (expr AS ?v)), ASK, CONSTRUCT (GRAPH blocks in templates produce quads), DESCRIBE; FROM / FROM NAMED; update forms (INSERT/DELETE DATA, DELETE WHERE, DELETE…INSERT…WHERE, WITH, USING, USING NAMED, and ADD/COPY/MOVE/CLEAR/DROP/CREATE); GRAPH, OPTIONAL, UNION, MINUS, VALUES, BIND, FILTER, EXISTS, NOT EXISTS, subqueries; every property path (^p, p/q, p|q, p+, p*, p?, !(p|^q), grouped); the SPARQL 1.1 function library (term tests, strings with character positions, numerics, dates, hashes) and XSD casts (xsd:integer(?x)); aggregates with DISTINCT, GROUP BY, HAVING; ORDER BY by value on expressions and aliases. A per-row type error drops the row in FILTER and leaves the variable unbound in BIND. Without FROM the default graph is the unnamed graph plus the property-graph projection. SERVICE answers only through a handler the embedding application sets (GraphStore.SetSPARQLServiceHandler); LOAD is refused — the store never fetches. Results can be written as SPARQL JSON/XML/CSV/TSV (SPARQLResult.WriteResults), and RDF/XML can be imported.

RDF 1.2 and SPARQL 1.2: triple terms <<( s p o )>> (object position only), reified triples << s p o ~ r >>, {| |} annotations and base-directed literals ("x"@ar--rtl) in N-Triples / N-Quads / Turtle / TriG, and SPARQL triple-term patterns with TRIPLE, isTRIPLE, SUBJECT, PREDICATE, OBJECT, LANGDIR, hasLANG, hasLANGDIR, STRLANGDIR. Use them to say things about a fact — its source, its confidence — and query that back:

INSERT DATA { _:r rdf:reifies <<( :alice :worksFor :acme )>> ; :source <doc1> ; :confidence 0.9 }

JSON-LD export refuses triple terms rather than flattening them.

Cypher. graph_cypher_query / db.QueryCypher runs a read-only openCypher / GQL subset over the property graph: MATCH, OPTIONAL MATCH, WITH, UNWIND, RETURN, UNION; labels are node types, relationship types are edge types; variable-length paths *m..n capped at 6 hops; aggregates, about 45 functions, $params. n.name falls back to title. Write clauses are refused by design, as are CALL, shortestPath, pattern predicates and temporal functions. Call graph_schema first.

MATCH (p:project)-[:depends_on]->(c {name: 'CortexDB'}) RETURN p.name

The property graph is readable as RDF. Everything extraction, upsert_entities and upsert_relations write also answers SPARQL, inference and SHACL, as read-only triples in graph <urn:cortexdb:graph:property> — nothing is copied, so nothing goes stale:

SELECT ?who WHERE { ?x cxr:depends_on ?y . ?y rdfs:label "CortexDB" . ?x rdfs:label ?who }

Call graph_schema first to learn which types and relations exist. Non-ASCII ids need the full <urn:cortexdb:node:…> form. Deleting or inserting projected triples is refused; change the property graph through its own APIs. GraphStore.SetPropertyGraphProjection(false) turns the projection off; exports leave it out.

Import and export speak N-Triples, N-Quads, Turtle, TriG and JSON-LD 1.1 (jsonld, also accepted as json-ld). JSON-LD import never fetches a remote @context: schema.org's is answered from memory, any other URL is refused with an error naming it, so inline the context instead.

Inference is semi-naive materialization over RDFS (rdfs:subClassOf, rdfs:subPropertyOf, rdfs:domain, rdfs:range) and OWL 2 RL (owl:inverseOf, owl:SymmetricProperty, owl:TransitiveProperty, owl:equivalentClass, owl:equivalentProperty, owl:sameAs, and the class expressions owl:someValuesFrom, owl:allValuesFrom, owl:hasValue, owl:intersectionOf, owl:unionOf, owl:oneOf, max cardinality). Every inferred triple records its rule and supports, so knowledge_graph_infer_explain traces it back to explicit triples. Declared over the projection, the OWL rules fix what extraction gets wrong: cxt:host owl:equivalentClass cxt:Host unifies spellings, cxr:depends_on owl:inverseOf cxr:depended_on_by answers the reverse question, cxn:entity%3Anode_e owl:sameAs cxn:entity%3Asds_e merges one machine stored under two names. A sameAs class larger than MaxSameAsClassSize (default 32) is reported in OversizedSameAsClasses, never half-materialized. OWL 2 RL keys and chains too: owl:FunctionalProperty / owl:InverseFunctionalProperty / owl:hasKey derive sameAs (the same e-mail is the same person), and owl:propertyChainAxiom (an RDF list, length ≥ 2) derives the chain. Contradictions — owl:disjointWith / owl:AllDisjointClasses, owl:propertyDisjointWith / owl:AllDisjointProperties, two different values of a functional property, owl:differentFrom / owl:AllDifferent against a derived sameAs, irreflexive and asymmetric properties, negative property assertions, owl:complementOf, owl:Nothing, a max cardinality of 0 — are reported in inconsistencies / inconsistency_count with the conflicting triple ids, never resolved; a sameAs class contradicted by differentFrom is not materialized.