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/importflow
  External structured-data import (CSV / MySQL-PG dumps) into RAG + knowledge-graph foundations, AI-assisted mapping optional.

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

pkg/core
  Storage engine (SQLite by default, PostgreSQL + pgvector by DSN), 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.

API Selection Cheat Sheet

Choose by the job to be done:

How To Choose

• If the input is a document and the goal is QA or retrieval, use SaveKnowledge / SearchKnowledge.
• If the input is dialogue, user preference, or session state, use SaveMemory / SearchMemory.
• If you do not want to hand-assemble prompt context, use KnowledgeMemory.
• If you need startup context or multi-layer wake-up memory for an assistant, use memoryflow.
• If you need standard RDF semantics, SPARQL, inference, or SHACL validation, use the knowledge graph APIs.
• If you need to transform a corpus into a graph and then analyze or export it, use graphflow.
• If you only need to expose the same capabilities to another agent, use tools or MCP instead of rebuilding the logic.

Short Mental Model

• Engine layer: pkg/core + pkg/graph
• Application facade: pkg/cortexdb
• Higher-level workflows: KnowledgeMemory, memoryflow, graphflow
• Agent exposure layer: GraphRAGTools, MCP

Common Compositions

• Chat assistant: memoryflow.IngestTranscript -> memoryflow.WakeUpLayers -> memoryflow.CloseSession
• Enterprise knowledge-base QA: SaveKnowledge -> SearchKnowledge
• Personal assistant memory: SaveMemory -> KnowledgeMemory.Recall
• Graph question answering: UpsertKnowledgeGraph -> QueryKnowledgeGraph -> ExplainKnowledgeGraphInference
• Codebase knowledge graph: graphflow.Pipeline.Run

Source Pointers

• Architecture and API selection overview: README.md, README_CN.md
• Knowledge APIs: pkg/cortexdb/knowledge_api.go
• Memory APIs: pkg/cortexdb/memory_api.go
• GraphRAG query path: pkg/cortexdb/graphrag.go
• KnowledgeMemory facade: pkg/cortexdb/brain.go
• Memory workflow service: pkg/memoryflow/service.go
• Corpus-to-graph pipeline: pkg/graphflow/pipeline.go
• External-data import: pkg/importflow/importer.go, pkg/importflow/source_dump.go, pkg/importflow/mcp.go
• Tool and MCP exposure: pkg/cortexdb/graphrag_tool_defs.go, pkg/cortexdb/mcp.go

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

Storage Backend (SQLite or PostgreSQL)

The DSN chooses the backend. Nothing else changes:

db, _ := cortexdb.Open(cortexdb.DefaultConfig("/var/lib/cortexdb/brain.db"))        // SQLite (default)
db, _ := cortexdb.Open(cortexdb.DefaultConfig("postgres://u:pw@host:5432/cortex"))  // PostgreSQL + pgvector

• A bare path still means a SQLite file, so existing configuration is unaffected.
• PostgresStore satisfies the same BrainStore contract as SQLiteStore: vectors, hybrid search, memory, RDF graph, SPARQL, ontology and the tool surface all run on either. db.Dialect().Kind() reports which.
• The registry (core.RegisterStore / core.OpenBrainStore) is compile-time, not a plugin system — storage is the hot path, and a process boundary would add an IPC round trip per search and make transactions impossible.
• Real differences: lexical search maps FTS5 unicode61 → tsvector @@ plainto_tsquery('simple') and the CJK trigram companion → LIKE + pg_trgm (pkg/core/fts_postgres.go carries the table); pgvector refuses to index past 2000 dimensions, so a wider model falls back to an exact scan and says so; pgvector itself is optional and a missing extension degrades to the in-Go scan.
• PostgreSQL tests are opt-in and loudly skipped: CORTEXDB_TEST_POSTGRES="postgres://..." go test ./... turns on 104 tests across pkg/core, pkg/graph, pkg/cortexdb, pkg/agentmem; without it the run prints 59 skips naming what is uncovered. Most are parity tests — one body, both databases, same answer required — because the failure mode is silent.
• External retrieval lanes are a different seam from storage: cortexdb.QuerySource (Name() + Search()) registered with WithQuerySource, asked for as QueryPrefetch{Kind: QueryPrefetchSource, Source: "<name>"}. A source returns ids and scores only — content is hydrated from the brain, ids the brain lacks are dropped, candidates still pass the filter and the normal fusion, and a source error fails the query rather than silently shrinking the result set. db.QuerySources() lists the registered ones. Adapters live outside pkg/ (see examples/17_query_source, Meilisearch over plain net/http).
• Not storage backends: Neo4j, Qdrant and similar. The graph is graph_nodes/graph_edges in the same database and the same transaction as the vectors, with SPARQL/RDFS/SHACL implemented over that SQL. pkg/sqldialect is dialect adaptation (placeholders, BLOB→BYTEA, error text, JSON accessors), not a query builder — it does not reach Cypher. Export with knowledge_graph_export instead and keep CortexDB as the system of record.

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.

Chinese (and other CJK) questions work in lexical mode as written. A sentence such as 微信机器人为什么从来不主动给我发提醒 is cut at function words (的, 了, 为什么, 那个, …), broken into character bigrams, matched by substring and ranked with BM25, then merged beside the word-index results — for memory, SearchKnowledge, SearchTextOnly and the search_text tool alike, on both backends, and inside the authorization gate. A row is returned only when it matches more than one word of the question (two separate stretches, or one of four characters or more, or the whole of a one-word question) and at least 30% of its content characters, 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.

Inference stays current by itself (on by default; WithAutoInference(false) turns it off). Every committed change is read from the change feed and applied with delete-and-rederive, asynchronously, so writers pay nothing; db.WaitForInference(ctx) waits until your own writes' consequences are in. With no RDFS/OWL axioms declared it is dormant and costs nothing. It never touches triples a SHACL rule produced; re-run the rules after a manual full refresh, which clears them.

Change feed. Every committed write to nodes, edges, triples, memories, knowledge and ontology schemas is appended to change_log in the same transaction — in commit order, exactly once, nothing from a rolled-back transaction. Read it by cursor with changes_since / db.Changes(ctx, after, limit) (resume from the last seq you saw; pruned says the cursor fell behind retention, so rebuild from current state), or db.SubscribeChanges in-process. Retention defaults to 7 days or 500k events.

_, _ = db.QueryKnowledgeGraph(ctx, cortexdb.KnowledgeGraphQueryRequest{
    Query: `INSERT DATA { cxr:depends_on owl:inverseOf cxr:depended_on_by }`,
})
_, _ = db.RefreshKnowledgeGraphInference(ctx, cortexdb.KnowledgeGraphInferenceRefreshRequest{})

Incremental refresh:

refresh, _ := db.RefreshKnowledgeGraphInference(ctx, cortexdb.KnowledgeGraphInferenceRefreshRequest{
    Mode: cortexdb.KnowledgeGraphInferenceRefreshModeIncremental,
    Triples: []cortexdb.KnowledgeGraphTriple{
        {
            Subject:   graph.NewIRI("https://example.com/Employee"),
            Predicate: graph.NewIRI("http://www.w3.org/2000/01/rdf-schema#subClassOf"),
            Object:    graph.NewIRI("https://example.com/Person"),
        },
    },
})
_ = refresh

SHACL supports targets sh:targetClass (with subclasses), sh:targetNode, sh:targetSubjectsOf, sh:targetObjectsOf; sh:property with any SHACL property path (sequence, sh:alternativePath, sh:inversePath, sh:zeroOrMorePath, sh:oneOrMorePath, sh:zeroOrOnePath); implicit class targets (a shape that is also an rdfs:Class); sh:class, sh:datatype, sh:nodeKind, sh:minCount, sh:maxCount, sh:min/maxInclusive, sh:min/maxExclusive, sh:minLength, sh:maxLength, sh:pattern + sh:flags, sh:languageIn, sh:uniqueLang, sh:in, sh:hasValue, sh:equals, sh:disjoint, sh:node, sh:not, sh:and, sh:or, sh:xone, sh:closed + sh:ignoredProperties, sh:lessThan, sh:lessThanOrEquals, sh:qualifiedValueShape + sh:qualifiedMinCount / sh:qualifiedMaxCount / sh:qualifiedValueShapesDisjoint, sh:deactivated, sh:severity, sh:message, on node and property shapes alike — all of SHACL Core (the W3C Core suite passes 98/98). SHACL-SPARQL too: sh:sparql SELECT constraints and SPARQL-based constraint components (sh:ConstraintComponent with sh:parameter and ASK/SELECT validators, $PATH), with $this, $value, $currentShape and parameters pre-bound. Results carry the constraint component IRI. Recursive shapes are refused with an error; any result makes conforms false, whatever its severity. Over the projection it is a quality gate for extracted graphs, e.g. every cxr:runs_on must point at an sh:class cxt:host. SHACL-AF rules: knowledge_graph_shacl_rules / db.ApplyKnowledgeGraphSHACLRules runs sh:TripleRule — with sh:condition, sh:order, sh:deactivated and node expressions sh:this, constants, sh:path (incl. sh:inversePath), sh:filterShape, sh:intersection, sh:union — to a fixpoint. Results are explainable inferred triples named shacl_triple_rule:*, and the shapes passed are the whole rule set: a rule left out is retracted on the next run.

report, _ := db.ValidateKnowledgeGraphSHACL(ctx, cortexdb.KnowledgeGraphSHACLValidateRequest{
    Shapes: []cortexdb.KnowledgeGraphTriple{
        {Subject: graph.NewIRI("https://example.com/PersonShape"), Predicate: graph.NewIRI(graph.RDFType), Object: graph.NewIRI(graph.SHACLNodeShape)},
        {Subject: graph.NewIRI("https://example.com/PersonShape"), Predicate: graph.NewIRI(graph.SHACLTargetClass), Object: graph.NewIRI("https://example.com/Person")},
    },
})
_ = report

What is actually in the graph, by type

db.Graph() reports the graph's own vocabulary, so an ontology or drift check never has to query graph_nodes / graph_edges directly. Raw SQL against those tables is pinned to one schema and one dialect and fails silently when either moves; these go through the same dialect-aware path as the rest of the package and are covered by the SQLite/PostgreSQL parity suite.

nodeTypes, _ := db.Graph().NodeTypeCounts(ctx) // map[string]int, untyped under ""
edgeTypes, _ := db.Graph().EdgeTypeCounts(ctx)

// Which type shapes the edges really have — how a declared relation is wrong.
shapes, _ := db.Graph().EdgeShapes(ctx, "uses")
// []EdgeShape{{EdgeType, FromType, ToType, Count}}

// Which nodes those edges run through — what is wrong.
pairs, _ := db.Graph().EdgeEndpointPairs(ctx, "uses")
// []EdgeEndpointPair{{EdgeType, From, To EdgeEndpoint{ID, NodeType, Content}, Count}}

Both edge queries take optional edge types, matched exactly as stored; passing none reports the whole graph.

Decision ledger

fact_provenance and the knowledge contract say how a fact is known. The ledger says why an action was taken: which facts it rested on, who took it, what it replaced, and what else was decided the same way.

A decision is a graph record, not a side table. It is a node decision:<id> typed Decision, whose content is the note and whose properties are kind, actor, at, verdict, subject plus the knowledge contract keys — so contract_tally counts a decision without being told about decisions, and expand_graph, render_graph_html, the live view and SPARQL all see it. Three edge types explain it: based_on (a premise), about (the subject) and supersedes (the decision it replaces).

rec, err := db.RecordDecision(ctx, cortexdb.DecisionRecordRequest{
    Kind:     cortexdb.DecisionKindReview, // load | review | action | assert (open vocabulary)
    Actor:    "liliang",
    Note:     "Held the ledger-svc release: riskd's rule source is unverified.",
    Verdict:  "hold",
    Subject:  "svc:ledger",
    Premises: []string{"svc:riskd", "fact:ledger-depends-on-riskd"}, // node ids and edge ids
})

chain, _ := db.DecisionChain(ctx, rec.ID, 0)     // premises with each one's grade and source
prior, _ := db.Precedents(ctx, cortexdb.PrecedentsQuery{Kind: "review", Subject: "svc:ledger"})
mine, _ := db.DecisionsBy(ctx, "liliang", 20)
_, _, _ = chain, prior, err

It fails closed and it fails before writing anything: an empty actor, an empty note, a premise or subject that does not exist, a supersedes target that is not a decision, or metadata ValidateContract refuses. By default a decision is stamped _grade=verified, _producer=human, _by=<actor> — a named actor signed it — and an agent recording its own decision says so with Producer and Grade.

A premise that is a fact is an edge, and graph_edges declares a foreign key on to_node_id, enforced on both backends. So the based_on edge is anchored on the fact's subject node and names the fact in its own premise_edge_id property; DecisionChain resolves it back and reports the edge's grade, not the anchor node's.

Tools (in-process and MCP), and the mirroring cortexdb.v1.DecisionService:

• decision_record — writes (read-only keys are refused it)
• decision_chain — reads
• decision_precedents — reads

Execution graph

An agent's own record of a task: one AgentRun node per run and one node per step — LLMCall, ToolCall, Retrieval, DecisionPoint, Validation or a kind of your own, which is also the node type and Cypher label — joined by HAS_STEP (run → step), TRIGGERED (a step → a step that consumed its output) and SPAWNED (a step → a sub-agent's run). Steps need no vector.

run, _ := db.StartRun(ctx, cortexdb.RunStart{Task: "checkout p99 alert", Agent: "devops-agent"})
plan, _ := db.RecordStep(ctx, cortexdb.StepStart{RunID: run.ID, Kind: cortexdb.StepKindLLMCall, Name: "plan"},
    cortexdb.StepEnd{Output: "check deps", Tokens: 640, CostUSD: 0.004})

// Two-phase: begin before the work (written as running, with its TRIGGERED
// edges), end after. A crash still leaves what was attempted.
st, _ := db.BeginStep(ctx, cortexdb.StepStart{RunID: run.ID, Kind: cortexdb.StepKindToolCall, Name: "restart_pool", Parents: []string{plan.ID}})
_, _ = db.EndStep(ctx, st.ID, cortexdb.StepEnd{Output: "pool recycled"}) // latency measured from begin
_, _ = db.FinishRun(ctx, run.ID, cortexdb.RunEnd{Outcome: "resolved"})

sum, _ := db.SummarizeRun(ctx, run.ID)                                // tokens, cost, open/failed steps, critical path, least confident step
up, _ := db.StepLineage(ctx, st.ID, cortexdb.LineageUpstream, 0)      // everything the action depended on
then, _ := db.ReplayRun(ctx, run.ID, someInstant)                     // the run as it stood then, from history
_, _, _ = sum, up, then

Every write fails before writing anything when the run is not running, a parent does not exist, the kind cannot be a label, or an attribute reuses a name the graph writes itself. A step ends once; a run finishes once. Steps are ordinary graph records, so Cypher, RecordDecision premises, expand_graph and the change feed all read them. Keep many runs in a file of their own if step nodes should not appear in a knowledge graph's schema.

Tools (in-process and MCP): execution_run_start, execution_step_begin, execution_step_end, execution_step_record, execution_run_finish — write; execution_run_get, execution_runs_list, execution_step_lineage, execution_run_replay — read.

Declared inference rules

apply_inference composes two hops. That is one rule shape; the engine behind it takes any Horn clause over graph edges — any number of premises, variables bound across them — forward-chained to a bounded fixpoint. apply_inference keeps its name and behaviour and now runs through that engine, so there is one derivation path and one explanation for both.

// Written the way a person writes it. Keywords are case-insensitive; a term
// starting with ? is a variable.
_, _ = db.SaveRules(ctx, cortexdb.RulesSaveRequest{Rules: []cortexdb.RuleDefinition{{
    ID:         "mortality",
    Text:       "IF instance_of(?x, ?c) AND subclass_of(?c, ?d) THEN instance_of(?x, ?d)",
    Confidence: 0.9,
}}})

// Dry run first; with neither rule_ids nor rules, every enabled rule runs.
plan, _ := db.ApplyRules(ctx, cortexdb.RulesApplyRequest{DryRun: true})
applied, _ := db.ApplyRules(ctx, cortexdb.RulesApplyRequest{})
_ = plan

// Why is that edge there?
why, _ := db.ExplainInference(ctx, cortexdb.InferenceExplainRequest{EdgeID: applied.CreatedEdgeIDs[0]})
// why.Explanation names the rule and its text; why.Trace is the premise chain,
// flattened in preorder.

Literal terms. A term starting with ? is a variable. Anything else is a literal, resolved against the stored nodes in this order: an exact node id first; otherwise Type:Name, matching every node whose node_type equals Type and whose name (the name property, or the node content) equals Name, both case-insensitively; otherwise a bare name matched the same way across all types. A literal matching several nodes matches all of them; one matching none is returned in unresolved_terms, so a rule that can never fire says so.

Derived edges carry inferred=true, provenance=rule, rule_id, rule_text, the exact support_edge_ids, and confidence = the minimum premise confidence times the rule's own. Re-running derives nothing new: an edge already there from the same rule is reported in unchanged_edge_ids, not rewritten.

Caps. Chaining stops at 16 rounds and 50 000 derived edges by default (max_iterations, max_derived). Hitting either is an error — graph.ErrRuleCapExceeded — and nothing is written, because a half-built closure in the graph is worse than none.

Rules persist in their own kg_rules table, not as graph nodes: a rule is configuration for the engine, not a fact about the world the graph describes, and a rule: node would show up in find_nodes, expand_graph and every export. The table is created the first time a rule is saved.

Tools: rules_save, rules_list, rules_delete, rules_apply (with dry_run), inference_explain. Engine: pkg/graph/rules*.go; facade: pkg/cortexdb/rules*.go.

Asking about the whole store

Retrieval answers "what is relevant to this query". Three APIs answer questions about the collection instead, and all three work identically on SQLite and PostgreSQL.

A threshold instead of a K. RangeSearchVector / RangeSearchText return every row within a distance of the query, and nothing outside it. Top-K always returns K rows however weak the last ones are; a range query returns what clears the bar and nothing when nothing does. That is the honest answer for "find all the near-duplicates of this", "does the store hold anything like this at all", and any threshold-driven decision.

near, err := db.RangeSearchText(ctx, "the backup vault is offline",
    cortexdb.VectorRangeOptions{Radius: 0.15})

Radius is a distance in the store's metric, not a similarity: under the default cosine it is 1 - similarity, so roughly 0.1 for near-identical text and 0.5 for loosely related. MaxResults 0 means every match. Tool: search_vector_range, which caps at 100 by default and reports truncated when the radius reached further than the cap — a trimmed range answer is otherwise indistinguishable from a complete one, which would make it an unlabelled top-K.

Counting. Aggregate runs count, sum, avg, min, max and group_by over a metadata field, optionally filtered and scoped to a collection. A group_by is also how to ask what values a field takes and how often. Tool: aggregate_metadata.

byKind, err := db.Aggregate(ctx, core.AggregationRequest{
    Type: core.AggregationGroupBy, GroupBy: []string{"kind"}, OrderBy: "count",
})

Metadata names in these requests are column references, not values, and cannot be bound as parameters — so they are checked against a conservative identifier shape and refused otherwise, rather than escaped. A name inside a JSON path may carry dots and hyphens (user.id, content-type); one that becomes bare SQL — GroupBy, which is aliased by its own text, plus OrderBy and the Having keys — may not.

Aggregating the vectors. VectorAggregate reduces the vectors themselves:

The medoid is the one worth reaching for: it names a row that exists, with its text, so the answer can be read and traced rather than only measured. It answers the consolidation question arithmetically, with no model in the loop. Tool: representative_records — medoid only, because a synthetic point can only reach a model as several hundred floats it can do nothing with.

Facets. SearchWithFacets filters a vector search by typed, nestable metadata facets and can return the per-value counts beside the hits. It is program-only on purpose: the filter language is a lot of schema for a model to get right, and the facet question a model actually has — what values, how many — is aggregate_metadata with a group_by.

Asking the graph about itself

Retrieval says what is relevant to a query; these say what the graph is. All work on both backends.

Its observed schema. GraphSchema reports which node and edge types exist and how many of each, which node-type pairs every edge type actually connects, and which property keys each node type carries. GraphPropertyValues reports what values one key actually takes. Call both before writing a traversal or a SPARQL query against a graph you have not inspected: a query naming a type the graph does not have still runs, matches nothing, and reads as an answer — and stored values are routinely codes, so a filter written from a key's name (color == "black" against rows that say BLK) returns nothing and looks like a fact. ontology_get answers the declared schema, which is opt-in and usually absent on graphs built by extraction; this is measured from the rows. The response carries a rendered text field, because this is read in a prompt. Tools: graph_schema, graph_property_values.

Its shape and its centres. GraphPageRank ranks nodes by structural importance — what a knowledge base is about, rather than what it says most often — with each node's label and type beside the score. GraphStatistics reports node and edge counts, average degree, density and connected components; a component count far above 1 means entities were written and never linked. GraphPredictEdges lists nodes one node is not connected to but arguably should be, which is two findings in one shape: a missing fact, or one entity stored twice. Read tied_at_top first — several unrelated nodes tied at exactly 1.0 means this graph's vectors cannot tell them apart, which is what short lexical hashes do to short entity names. Tools: rank_graph_nodes, graph_statistics, predict_graph_edges.

rank_graph_nodes reads a cached ranking. Scores live in a side table (graph_pagerank_scores) with the time they were computed; a call on an unchanged graph is an indexed LIMIT read (on a 2000-node graph: 0.11ms p50 against 16ms recomputing), and a change to the graph's nodes or edges is detected in the database — on SQLite by rowid maxima plus triggers on deletes and endpoint rewrites, so writes from another process count; on PostgreSQL by a topology aggregate — and triggers a recompute. The answer carries cached, computed_at, stale, stale_reason; refresh forces a recompute, allow_stale serves an out-of-date ranking without paying for one, max_age_seconds bounds its age. From Go: GraphPageRankOptions.Cache (PageRankCacheAuto / Refresh / AllowStale; the zero value computes fresh as before), RefreshPageRankCache, InvalidatePageRankCache, and StartPageRankRefresher(ctx, interval, …) to keep it warm on a timer.

Whole-corpus questions (GraphRAG global search). global_search answers what retrieval cannot — "what are the main themes", "what does this brain cover" — by map-reducing over community reports. The caller chooses it; no query is routed to it by its wording. build_community_hierarchy detects the entity graph's communities with Leiden — every community connected at every level, which Louvain does not guarantee; HierarchyOptions.Algorithm selects Louvain — and keeps every level (0 = finest, each level up merges the one below), then writes a report per community bottom-up: level 0 from its entities and relations, higher levels from their children's reports. global_search takes a level (default: the coarsest, fewest reports, cheapest map) and builds the hierarchy on first use. With a model (graphflow.JSONGenerator; in the MCP binary CORTEXDB_LLM_*) reports and answer are the model's; without one reports are assembled deterministically and global_search returns the lexically most relevant reports unsynthesised (mode: "no_model"). Go: graphflow.BuildCommunityHierarchy, graphflow.GlobalSearch(…, GlobalSearchOptions{Level: &l}), graph.GraphStore.HierarchicalCommunities. Registered by graphflow.AddGlobalSearchMCPTools in cortexdb-mcp-stdio (local mode) and in graphflow.NewMCPServer.

Disambiguating a name against the graph. DisambiguateMentions resolves an ambiguous name using the other names given with it: it finds the shortest paths between this mention's candidates and the others', renders each as a sentence, and ranks by that support. Steps one to four are deterministic and live here; the choice is the caller's, so a caller with no model takes the top rank and one with a model reads the evidence — and either way can say afterwards why. A mention nothing connects to is unresolved, never the nearest string match, and a bound that stopped the search is reported apart from an absence.

res, err := db.DisambiguateMentions(ctx, []string{"Claude", "MCP", "OpenClaw"},
    cortexdb.DisambiguationOptions{NodeTypes: []string{"entity", "project", "protocol", "tool"}})

Pass NodeTypes on any brain that keeps documents and chunks as graph nodes. Without it, one document title holding two of the mentions matches both by substring and scores a perfect 1.0 for each — a coincidence of two words that ties with the real entity and resolves nothing. Tool: disambiguate_mentions.

Resolving duplicate entities: link first, merge later. graphflow.ResolveEntities scores each candidate pair on name similarity, shared neighbours and type agreement (plus the model's grouping, if an LLM is given). Only a score of 0.95 or more merges; 0.85–0.95 writes a possiblySame edge carrying that evidence, graded held, which contract_needs_attention lists. Grade the edge verified and the next pass merges it; refused keeps the pair apart. Spelling alone never merges two differently spelled names, and two entities with the same name and no neighbour in common (two main.go files, Mercury the planet and the element) are linked, not merged. ResolveOptions{Mode: graphflow.ResolveMergeAll} is the old unscored merge.

Why a fact ended. Every row that leaves the live graph — superseded, retracted, merged, removed with its document — lands in graph_node_history/graph_edge_history with reason, superseded_by and producer. Read it with db.NodeHistory / db.EdgeHistory, or from the invalidation on each retracted or changed row of graph_diff. A caller that knows more than the default says so with graph.WithInvalidation(ctx, …).

Path retrieval for multi-hop questions. Chunk search ranks passages by how much they look like the question; for "how is Alice Chen connected to Kestrel?" the passage stating the middle link ("Borealis Labs built Kestrel") does not look like it, and one that merely shares its words does. SearchPaths walks the graph between the entities the question names — bounded breadth-first search, at most MaxDepth edges (default 3), scored decay^(hops-1) times the product of relation weights — and returns each chain as edges that cite the chunk they were extracted from (chunk_ids / source_chunk_id on the edge). With one seed it returns the paths leaving it, which is the shape of "the city of the company Alice works for". Paths never run through chunk or document nodes unless IncludeBookkeeping is set: a shared chunk is a co-mention, not a relation.

resp, err := db.SearchPaths(ctx, cortexdb.ToolSearchPathsRequest{
    EntityNames:      []string{"Alice Chen", "Kestrel"},
    RelationPolicies: graph.RelationPolicies{"co_occurs_with": {Weight: 0.2, MaxDepth: 1}},
    WithText:         true,
})
// resp.Paths[i].Edges[j].ChunkIDs — the evidence, link by link; resp.ChunkIDs — all of it, in path order

GraphRAGQueryOptions.ReturnPaths (return_paths on search_graphrag_lexical) adds the same chains to a GraphRAG result, seeded by the plan's entity names or, without any, by the entities the top three chunks mention; chunks and context are unchanged. Tool: search_paths.

Per-relation-type weight and depth. graph.RelationPolicies maps a relation type to {Weight, MaxDepth} — weight multiplies a path's score (0 = 1.0, negative = never follow), max depth is the farthest hop from the start at which the type is still followed — with "*" for every unlisted type. It is accepted by SearchPaths, expand_graph (relation_policies; the response then carries a score per node and limit keeps the best), Neighbors/ScoredNeighbors (TraversalOptions.Relations) and HybridSearch (GraphFilter.Relations, where GraphScore becomes the relation-weight product over distance+1). Unset, every one of them behaves exactly as before.