AutoGineer
Generated banner for CortexDB
Generated logo for CortexDB

CortexDB

Memory framework

First committed by liliang-cn

Published in liliang-cn/cortexdb. Publisher page

478 GitHub stars

What it is

Local-first AI agent memory with a knowledge graph, ontology constraints, and traceable reasoning—all in one SQLite file.
— the description by liliang-cn

AutoGineer overview, from the brain’s own files

CortexDB is a memory framework designed for AI agents that provides persistent, structured, and traceable storage. It integrates a knowledge graph with vector and full-text search capabilities, allowing agents to store and retrieve information with semantic context. The system supports complex data types, including media, and maintains a history of changes to the graph and ontology. It is built to be portable, operating as a pure Go library or a service, and supports multi-agent environments through shared gRPC connections. With features like SHACL-based ontology governance and traceable reasoning, it enables agents to manage project context, session history, and durable facts effectively.

How it works

Memory model: Hybrid

AutoGineer overview, from the brain’s own files

CortexDB stores all memory and knowledge graph data in a single SQLite file. It uses a hybrid retrieval approach that combines vector search, full-text search, and graph traversal. Agents interact with the database through a set of tools that allow them to remember facts, recall information, and manage an ontology. The system tracks the history of every change, including additions, replacements, and retractions, and provides a live 3D view for visualizing the graph and monitoring agent activity.

Folders
FolderRoleFiles
.githubagent-config6
docsdocs54
examplesexamples41
pkgsource-code1671
scriptsscripts2
skillsagent-instructions6
.agentsfolder3
.claude-pluginfolder1
clientsfolder72
cmdfolder85
deployfolder10
internalfolder8
pluginsfolder79
protofolder9

The agent reads

Requirements

Runtimes: Go

Databases: PostgreSQL, SQLite

API keys (by name): CORTEXDB_EMBED_API_KEY, CORTEXDB_GRPC_TOKEN, CORTEXDB_MEDIA_EMBED_API_KEY, CORTEXDB_MEDIA_TRANSCRIBE_API_KEY, OPENAI_API_KEY

Works with: Claude Code

Set it up

  1. This brain runs code automatically: 4 hooks (codex). Review plugins/cortexdb/hooks/hooks.json before opening the folder in Claude Code. No step below turns a hook on for you.

    • plugins/cortexdb/hooks/hooks.json: ${CLAUDE_PLUGIN_ROOT}/bin/cortexdb-session-start
    • plugins/cortexdb/hooks/hooks.json: ${CLAUDE_PLUGIN_ROOT}/bin/cortexdb-recall
    • plugins/cortexdb/hooks/hooks.json: ${CLAUDE_PLUGIN_ROOT}/bin/cortexdb-file-context
    • plugins/cortexdb/hooks/hooks.json: ${CLAUDE_PLUGIN_ROOT}/bin/cortexdb-session-end
  2. Not scanned by AutoGineerThe author’s README also describes installing it as a Claude Code plugin marketplace. Read its install section: AutoGineer did not scan that path. https://github.com/liliang-cn/cortexdb/blob/d39714c86784edd23d42ce152a0243464ad2b15a/README.md#install
  3. Not scanned by AutoGineerThe author’s README also describes installing it with go install. Read its install section: AutoGineer did not scan that path. https://github.com/liliang-cn/cortexdb/blob/d39714c86784edd23d42ce152a0243464ad2b15a/README.md#install

  4. First committed by liliang-cn. Published in liliang-cn/cortexdb. Licence: MIT License.

Usage

AutoGineer overview, from the brain’s own files

  • Integrating persistent memory into AI agents via Go, Python, Rust, or Node.js clients.
  • Sharing a centralized knowledge base across multiple agents or machines using the gRPC server.
  • Managing project-specific context and session history for coding agents like Claude Code.
  • Visualizing and auditing agent memory and reasoning through a live 3D graph interface.
“Remember that Alice prefers tabs.”
The agent saves the fact 'Alice prefers tabs' into the user-scoped knowledge memory.
“What does Alice prefer?”
The agent retrieves the stored preference from the knowledge memory and provides the answer.

Documentation by liliang-cn

CortexDB

Image: Go Reference Image: CI Image: codecov Image: License: MIT

AI memory and a knowledge graph in one SQLite file. Pure Go, no service to run, works without an embedding model.

Image: The CortexDB live view: two recalls light up the graph, then the Recalls, Ontology and Library pages

Install

Go librarygo get github.com/liliang-cn/cortexdb/v2
Claude Code/plugin marketplace add liliang-cn/cortexdb, then /plugin install cortexdb@cortexdb
Codexcodex plugin marketplace add liliang-cn/cortexdb && codex plugin add cortexdb@cortexdb
Claude Code mod (optional)/plugin install cortexdb-live@cortexdb
DeepSeek Harnessdsh plugin --profile web add "github:liliang-cn/cortexdb#semver:^2&path:/plugins/dsh-cortexdb-memory" (guide)
Obsidianunzip a release's cortexdb-obsidian.zip into <vault>/.obsidian/plugins/ (guide)
Shared-brain servergo install github.com/liliang-cn/cortexdb/v2/cmd/cortexdb-grpc@latest
Clientscargo add cortexdb-client · pip install cortexdb-client · npm install cortexdb-client

Use

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

The plugin gives Claude Code and Codex one global brain at ~/.cortexdb/cortexdb.db, /remember, /recall and an auto-recall hook. A session starts with an index of what the brain knows about its project, an agent about to open a file is told what happened to it before, and a session's durable facts are captured with <private> text and credentials kept out. Point several agents or machines at one cortexdb-grpc and they share the same memory and graph.

In Codex, review and trust the plugin hooks in /hooks to activate automatic recall. See the plugin guide for setup and cortexdb-mcp --doctor --self-test diagnostics (v2.119.0+).

Live view

A web UI over the brain, local or shared: run cortexdb-mcp-stdio --graph-3d, or ask the agent to call serve_graph_3d.

  • Graph: the knowledge graph in 3D. A recall from any agent or machine lights the records it returned, and the Live feed says who asked what.

  • Recalls: every recall with its plan, its hits and why each ranked (CORTEXDB_RECALL_LOG=1).

  • Changes and Activity: every fact added, replaced or retracted, and the tool calls the brain handled.

  • Ontology: the declared types held against what the records are actually typed as.

  • Library: the same memories as a reading room, shelved by project.

Read-only, light by default, works on a phone, in English or Chinese (the toggle in the top bar). See the guide.

Claude Code mod

cortexdb-live is an optional mod that runs inside Claude Code on top of the cortexdb plugin. Install it after the plugin:

/plugin install cortexdb-live@cortexdb

The mod calls three of the plugin's tools itself, and a hook gets no permission prompt, so allow them once in ~/.claude/settings.json (not needed in bypass mode):

"permissions": {
  "allow": [
    "mcp__plugin_cortexdb_cortexdb__knowledge_memory_recall",
    "mcp__plugin_cortexdb_cortexdb__graph_statistics",
    "mcp__plugin_cortexdb_cortexdb__memory_save"
  ]
}

Without them the status line names the missing rules.

  • Planned recall. Before the brain is searched, haiku turns each prompt into keywords in Chinese and English, aliases, entity names and a retrieval mode. A bare "ok" or "go ahead" searches nothing. The band above the prompt shows what was recalled; expand it to see the plan and every hit. Hide lasts until the next recall; /cortexdb-show brings the hidden one back.

  • Status line. Which brain the session uses, its node count and how long the last recall took, or why the brain can't be reached.

  • Capture. 90 seconds after a session goes idle, haiku distils the new part of the conversation into durable memories (auto:<session>:<slug>). Each later pass replaces a memory under the same slug rather than adding a copy. Older memories a new one makes untrue (a host moved, a decision reversed) are marked superseded: kept, but no longer recalled as current. The project's Claude Code file memory (~/.claude/projects/<project>/memory/) is shown to haiku as already recorded, so a capture does not restate a note in other words. A prompt with an image attached is not recalled for.

Haiku runs on Claude Code's own model access, so no API key is needed. Language: /config → cortexdb-live → language (auto, zh, en). The mod honours the plugin's own switches: cortexdb-recall --disable and cortexdb-session-end --disable turn recall and capture off for both. While the mod runs, the plugin's shell recall and capture hooks stand down, so nothing is done twice. Codex keeps those hooks. Mods are an early-access Claude Code feature.

What's inside

  • Vectors (HNSW, IVF, flat, binary codes), FTS5 full-text search, hybrid and graph retrieval

  • EmbeddedConfig for small devices: an SQ8 index, bounded SQLite caches, snapshots that survive a power cut — 100k 768-d vectors open in 0.28 s with a 193 MB heap

  • RAG knowledge, scoped agent memory, context packs with sources — memories say whether they were verified or are a guess, and recall keeps the two apart

  • RDF 1.2 knowledge graph: SPARQL 1.1/1.2, RDFS + OWL 2 RL inference, SHACL Core + SHACL-SPARQL, RDF/XML import — passing the W3C SPARQL 1.1/1.2, RDF 1.2 (Turtle, TriG, N-Triples, N-Quads, RDF/XML) and SHACL test suites; RDFS and OWL 2 RL are covered by the repo's own tests — and read-only Cypher

  • Palantir-style ontology with governed actions

  • 100+ tools, in-process or over MCP

  • serve_graph_3d: a live 3D view to find, ask, query and expand, on desktop or phone, with a Changes page that says in words what was added, replaced or retracted as it happens, and an Entity page with each relation, why its value is in effect and what it replaced; or the same brain as a library, each memory a book on its project's shelf

  • import_agent_memory: bring in what Claude Code, Codex and DeepSeek Harness already remember — memory notes, CLAUDE.md / AGENTS.md, Codex's memories, and optionally past sessions distilled into memories — into a local or shared brain

  • Change feed: every committed write, in order, exactly once

  • Observability: a request id and a W3C trace (traceparent) from MCP through gRPC to the trace and the recall log, recalls that explain themselves and say when they were degraded, embedder health in /metrics and /healthz, and an opt-in recall log with a /recalls page

  • Images, recordings and videos (ingest_media): found by a text question through their caption, visible text and transcript, a hit saying where in the file — with or without an embedder; with a CLIP-style media embedder also by what they show, and by an image (search_media)

  • History of the graph and the ontology: for an entity, relation, triple or schema, every version, when and why it changed, and which one is in effect and why (graph_history, knowledge_graph_history, ontology_history); as_of on SPARQL, find, expand and Cypher; an entity timeline, an As of pin and an ontology version list in the live view

  • SQLite by default, PostgreSQL + pgvector with a postgres:// DSN

Environment

VariableMeaning
CORTEXDB_PATHDatabase file (default ~/.cortexdb/cortexdb.db)
CORTEXDB_REMOTEUse a shared cortexdb-grpc at host:port (plaintext) or https://host (TLS, behind a proxy) instead of a local file
CORTEXDB_GRPC_TOKENBearer token for that server
CORTEXDB_GRPC_ADDRServer listen address (default 127.0.0.1:47821)
CORTEXDB_EMBED_BASE_URL / CORTEXDB_EMBED_API_KEYcortexdb-mcp-stdio: OpenAI-compatible embeddings endpoint and its key (fall back to OPENAI_BASE_URL / OPENAI_API_KEY); unset = lexical mode
OPENAI_BASE_URL / OPENAI_API_KEYServer: the embeddings endpoint and key (cortexdb-grpc reads only these, not CORTEXDB_EMBED_BASE_URL); unset = lexical mode
CORTEXDB_EMBED_MODEL / CORTEXDB_EMBED_DIMEmbedding model and dimension, for both (default text-embedding-3-small / 1536)
CORTEXDB_VECTOR_INDEX / CORTEXDB_BINARY_OVERSAMPLEServer: hnsw (default) or, on a SQLite store, binary (1-bit codes in memory, 1/32 of the vectors, each search rescored from the stored vectors, no snapshot); the oversample is the binary shortlist multiplier, from 1 to 1000 (default 8)
CORTEXDB_REVIEW_GATEServer and cortexdb-mcp-stdio: 1 leaves proposed and rejected documents and memories out of search and recall (default off; a curation filter, not access control)
CORTEXDB_SLOW_MSServer: log calls slower than this, with the time each stage took (default 1000, 0 = none)
CORTEXDB_TRACE / CORTEXDB_TRACE_FILEServer: log every call; also append the records to a JSON-lines file
CORTEXDB_LOG_FORMAT / CORTEXDB_LOG_LEVELServer: text (logfmt, default) or json; debug, info (default), warn, error
CORTEXDB_TRACE_MAX_MB / CORTEXDB_TRACE_KEEP / CORTEXDB_TRACE_MAX_AGE_DAYSServer: rotate the trace file at this size (100), keep this many old files (5) for at most this many days (30)
CORTEXDB_EMBED_PROBE_SECONDSServer: probe the embedder this often, for /healthz and /metrics (default 60, 0 = off)
CORTEXDB_RECALL_LOGServer and cortexdb-mcp-stdio: 1 keeps a log of recalls — queries included — for the /recalls page and the recall_log_* tools (default off)
CORTEXDB_RECALL_LOG_DAYS / CORTEXDB_RECALL_LOG_MAX_ROWSHow long (30 days) and how many (100000) recalls the log keeps
CORTEXDB_MEDIA_VISION_URL / CORTEXDB_MEDIA_VISION_MODELServer and cortexdb-mcp-stdio: an Ollama vision model that captions images and video frames for ingest_media (e.g. http://localhost:11434 / qwen3.5:4b)
CORTEXDB_MEDIA_TRANSCRIBE_URL / CORTEXDB_MEDIA_TRANSCRIBE_MODEL / CORTEXDB_MEDIA_TRANSCRIBE_API_KEYAn OpenAI-compatible …/v1 transcription endpoint for audio and the sound of videos (OpenAI, or whisper.cpp's whisper-server --inference-path /v1/audio/transcriptions --convert)
CORTEXDB_MEDIA_EMBED_URL / CORTEXDB_MEDIA_EMBED_MODEL / CORTEXDB_MEDIA_EMBED_API_KEYA CLIP-style embedding endpoint (infinity's /embeddings with modality) that puts images, video frames and text in one space, so an image is found by what it shows and search_media takes an image as the query
CORTEXDB_MEDIA_EMBED_AUDIO / CORTEXDB_MEDIA_EMBED_MIN_SCORE1 when that model embeds sound too (CLAP); the cosine a media vector must reach to be a hit (0.2)
CORTEXDB_MEDIA_FRAME_INTERVAL / CORTEXDB_MEDIA_MAX_BYTESSeconds between the video frames captioned (10, 0 = none; needs ffmpeg), and the size cap of one file (32 MiB)

Docs

Website · Guide (full feature reference) · Examples · Changelog · 中文

License

MIT

README_CN.md

CortexDB

Image: Go Reference Image: CI Image: codecov Image: License: MIT

一个 SQLite 文件装下 AI 记忆与知识图谱。纯 Go，不用额外跑服务，没有 embedding 模型也能用。

Image: CortexDB 实时视图：两次召回点亮图谱，然后是召回、本体和图书馆页面

安装

Go 库go get github.com/liliang-cn/cortexdb/v2
Claude Code/plugin marketplace add liliang-cn/cortexdb，再 /plugin install cortexdb@cortexdb
Codexcodex plugin marketplace add liliang-cn/cortexdb && codex plugin add cortexdb@cortexdb
Claude Code mod（可选）/plugin install cortexdb-live@cortexdb
DeepSeek Harnessdsh plugin --profile web add "github:liliang-cn/cortexdb#semver:^2&path:/plugins/dsh-cortexdb-memory"（说明）
Obsidian把 release 里的 cortexdb-obsidian.zip 解压到 <vault>/.obsidian/plugins/（说明）
共享大脑服务端go install github.com/liliang-cn/cortexdb/v2/cmd/cortexdb-grpc@latest
客户端cargo add cortexdb-client · pip install cortexdb-client · npm install cortexdb-client

使用

db, _ := cortexdb.Open(cortexdb.DefaultConfig("brain.db"))
defer db.Close()
brain := db.KnowledgeMemory()
_, _ = brain.Remember(ctx, cortexdb.KnowledgeMemoryRememberRequest{MemoryID: "alice-tabs", UserID: "alice", Scope: "user", Content: "Alice 偏好 tab 缩进。"})
rec, _ := brain.Recall(ctx, cortexdb.KnowledgeMemoryRecallRequest{Query: "Alice 偏好什么?", UserID: "alice"})
fmt.Println(rec.ContextPack.Text)

插件给 Claude Code 和 Codex 一个全局大脑 ~/.cortexdb/cortexdb.db，带 /remember、/recall 和自动召回 hook。会话一开始就拿到大脑里关于当前项目的近况索引；agent 打开一个文件前，会先被告知这个文件以前发生过什么；会话里的长期事实会被自动记下，<private> 里的内容和密钥不会进去。多个 agent、多台机器指向同一个 cortexdb-grpc，就共享同一份记忆和图谱。

Codex 中需要在 /hooks 审阅并信任插件 hooks，自动召回才会运行。 配置和 cortexdb-mcp --doctor --self-test 诊断用法见插件指南；诊断命令需要 v2.119.0 或更新版本的二进制。

实时视图

大脑之上的网页界面，本地库和共享大脑都能用：运行 cortexdb-mcp-stdio --graph-3d，或让 agent 调用 serve_graph_3d。

  • 图谱：3D 知识图谱。任何 agent、任何机器发起召回，命中的记录都会亮起来，实时栏写明谁问了什么。

  • 召回：每一次召回的检索计划、命中和每条的排名原因（需 CORTEXDB_RECALL_LOG=1）。

  • 变更和活动：每条事实的新增、替换、撤回，以及大脑处理过的工具调用。

  • 本体：声明的类型，对照记录实际用的类型。

  • 图书馆：同一批记忆换成阅览室，按项目上架。

只读，默认浅色，手机也能用，中英文随时切换（顶栏的语言按钮）。详见指南。

Claude Code mod

cortexdb-live 是一个可选的 mod，运行在 Claude Code 里，叠在 cortexdb 插件之上。装好插件后再装：

/plugin install cortexdb-live@cortexdb

mod 会自己调用插件的三个工具，而钩子里的调用不会弹权限确认，所以要在 ~/.claude/settings.json 里允许一次（bypass 模式下不需要）：

"permissions": {
  "allow": [
    "mcp__plugin_cortexdb_cortexdb__knowledge_memory_recall",
    "mcp__plugin_cortexdb_cortexdb__graph_statistics",
    "mcp__plugin_cortexdb_cortexdb__memory_save"
  ]
}

没加的话，状态栏会提示缺哪几条。

  • 规划过的召回：检索之前，haiku 先把每条 prompt 拆成中英文关键词、别名、实体名和检索方式。只是「好」「发」这类确认就不检索。输入框上方显示召回了什么，展开能看到查询规划和每一条结果。隐藏后，下一次召回会自动重新出现；想马上找回刚隐藏的那条，用 /cortexdb-show。

  • 状态栏：当前连的是哪个大脑、节点数、上次召回用时；连不上时显示原因。

  • 自动记忆：会话空闲 90 秒后，haiku 把新增的对话提炼成长期记忆（auto:<会话>:<slug>）。之后再提炼时，同一个 slug 是替换而不是重复写一条。新记忆推翻的旧记忆（换了主机、改了决定）会被标记为已替代：仍然保留，但不再作为当前事实被召回。项目在 Claude Code 里的文件记忆（~/.claude/projects/<项目>/memory/）会作为"已记录"交给 haiku，提炼时不会换个说法再记一遍。带图片的提问不做召回。

haiku 用的是 Claude Code 自己的模型额度，不需要 API key。语言：/config → cortexdb-live → language（auto、zh、en）。mod 认插件原有的开关：cortexdb-recall --disable、cortexdb-session-end --disable 会同时关掉两边的召回和记忆。mod 运行时，插件的 shell 召回和记忆钩子会自动让开，不会重复做。Codex 仍然用那两个钩子。mod 是 Claude Code 的早期功能。

里面有什么

  • 向量（HNSW、IVF、Flat、二值编码）、FTS5 全文检索、混合检索与图检索

  • EmbeddedConfig，给小设备用：SQ8 量化索引、有上限的 SQLite 缓存、断电也不丢的索引快照——10 万条 768 维向量 0.28 秒打开，堆内存 193 MB

  • RAG 知识、分作用域的 agent 记忆、带来源的上下文包——记忆标明是验证过的还是猜测，召回时两者分开

  • RDF 1.2 知识图谱：SPARQL 1.1/1.2、RDFS + OWL 2 RL 推理、SHACL Core + SHACL-SPARQL、RDF/XML 导入——通过 W3C 的 SPARQL 1.1/1.2、RDF 1.2（Turtle、TriG、N-Triples、N-Quads、RDF/XML）和 SHACL 官方测试集，RDFS 和 OWL 2 RL 用的是仓库自己的测试——以及只读 Cypher

  • Palantir 风格的 ontology，带受治理的动作

  • 100+ 工具，进程内调用或走 MCP

  • serve_graph_3d：实时 3D 视图，可查找、提问、查询、展开，桌面和手机都能用；Changes 页面即时用文字写出新增、取代、撤回了什么，Entity 页面列出每条关系、当前值为什么生效、取代了什么；也可以切成图书馆，每条记忆是它所属项目书架上的一本书

  • import_agent_memory：把 Claude Code、Codex 和 DeepSeek Harness 已有的记忆导进来——记忆笔记、CLAUDE.md / AGENTS.md、Codex 的记忆库，也可以把历史会话提炼成记忆——本地大脑和共享大脑都行

  • 变更事件流：每次已提交的写入，按顺序、恰好一次

  • 可观测性：request id 和 W3C 链路（traceparent）从 MCP 经 gRPC 贯穿到 trace 和召回日志，召回能解释自己、降级时直说，/metrics 和 /healthz 里有向量服务的健康状况，可选开启的召回日志带 /recalls 页面

  • 图片、录音和视频（ingest_media）：凭说明文字、图中文字和转写稿用文字问题找到，命中会说出在文件的哪个时间点；有没有嵌入模型都行；配上 CLIP 类媒体嵌入模型后还能按画面内容找，也能以图搜图（search_media）

  • 图谱和 ontology 的历史：任何实体、关系、三元组或 schema，都能看到它的每个版本、什么时候因为什么改的、现在哪个版本生效以及为什么（graph_history、knowledge_graph_history、ontology_history）；SPARQL、查找、展开和 Cypher 都支持 as_of；实时视图里有实体时间线、As of 固定时刻和 ontology 版本列表

  • 默认 SQLite，换成 postgres:// DSN 就跑在 PostgreSQL + pgvector 上

环境变量

变量含义
CORTEXDB_PATH数据库文件（默认 ~/.cortexdb/cortexdb.db）
CORTEXDB_REMOTE连到共享的 cortexdb-grpc，不用本地文件：host:port 是明文，https://host 走 TLS（放在反向代理后面时用）
CORTEXDB_GRPC_TOKEN该服务的 Bearer token
CORTEXDB_GRPC_ADDR服务端监听地址（默认 127.0.0.1:47821）
CORTEXDB_EMBED_BASE_URL / CORTEXDB_EMBED_API_KEYcortexdb-mcp-stdio：OpenAI 兼容的 embeddings 端点和它的 key（没设时退回 OPENAI_BASE_URL / OPENAI_API_KEY）；不设就是词法模式
OPENAI_BASE_URL / OPENAI_API_KEY服务端：embeddings 端点和 key（cortexdb-grpc 只读这两个，不读 CORTEXDB_EMBED_BASE_URL）；不设就是词法模式
CORTEXDB_EMBED_MODEL / CORTEXDB_EMBED_DIMembedding 模型和维度，两边都读（默认 text-embedding-3-small / 1536）
CORTEXDB_REVIEW_GATE服务端和 cortexdb-mcp-stdio：1 时待审和被拒的文档、记忆不进搜索和召回（默认关；这是整理用的过滤，不是权限控制）
CORTEXDB_SLOW_MS服务端：超过这个毫秒数的请求记日志，带各阶段耗时（默认 1000，0 不记）
CORTEXDB_TRACE / CORTEXDB_TRACE_FILE服务端：每个请求都记；同时把记录追加到 JSON lines 文件
CORTEXDB_LOG_FORMAT / CORTEXDB_LOG_LEVEL服务端：text（logfmt，默认）或 json；debug、info（默认）、warn、error
CORTEXDB_TRACE_MAX_MB / CORTEXDB_TRACE_KEEP / CORTEXDB_TRACE_MAX_AGE_DAYS服务端：trace 文件到这个大小切分（100），保留这么多个旧文件（5），最长这么多天（30）
CORTEXDB_EMBED_PROBE_SECONDS服务端：每隔多少秒探测向量服务，供 /healthz 和 /metrics（默认 60，0 关闭）
CORTEXDB_RECALL_LOG服务端和 cortexdb-mcp-stdio：1 记录召回日志（含查询文本），供 /recalls 页面和 recall_log_* 工具（默认关闭）
CORTEXDB_RECALL_LOG_DAYS / CORTEXDB_RECALL_LOG_MAX_ROWS召回日志保留多久（30 天）、最多多少条（100000）
CORTEXDB_MEDIA_VISION_URL / CORTEXDB_MEDIA_VISION_MODEL服务端与 cortexdb-mcp-stdio：给 ingest_media 的图片和视频帧写说明的 Ollama 视觉模型（如 http://localhost:11434 / qwen3.5:4b）
CORTEXDB_MEDIA_TRANSCRIBE_URL / CORTEXDB_MEDIA_TRANSCRIBE_MODEL / CORTEXDB_MEDIA_TRANSCRIBE_API_KEY转写音频和视频声音的 OpenAI 兼容 …/v1 接口（OpenAI，或 whisper.cpp 的 whisper-server --inference-path /v1/audio/transcriptions --convert）
CORTEXDB_MEDIA_EMBED_URL / CORTEXDB_MEDIA_EMBED_MODEL / CORTEXDB_MEDIA_EMBED_API_KEYCLIP 类嵌入接口（infinity 带 modality 的 /embeddings），把图片、视频帧和文字放进同一个向量空间：图片能按画面内容被找到，search_media 能以图搜图
CORTEXDB_MEDIA_EMBED_AUDIO / CORTEXDB_MEDIA_EMBED_MIN_SCORE该模型也能嵌入声音（CLAP）时设 1；媒体向量算作命中所需的最低余弦（0.2）
CORTEXDB_MEDIA_FRAME_INTERVAL / CORTEXDB_MEDIA_MAX_BYTES视频每隔几秒取一帧写说明（10，0 不取；需要 ffmpeg），单个文件的大小上限（32 MiB）

文档

官网 · 指南（完整功能一览） · 示例 · 更新日志 · English

License

MIT

512 files · 501 not served here

Advantages

Limitations

Security

Risk level: Medium risk

This brain runs

Agent instructions that run or fetch something (86)

  • .agents/skills/cortexdb/SKILL.md: Run with `GOMEMLIMIT` set below the device's memory so the garbage collector works before the kernel does.
  • .agents/skills/cortexdb/SKILL.md: 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.
  • .agents/skills/cortexdb/SKILL.md: From a shell: `cortexdb-mcp --import-agent-memory [--sessions] [--since 30d] [--max N] [--dry-run]`.
  • .agents/skills/cortexdb/SKILL.md: re-run the rules after a manual full refresh, which clears them.
  • .agents/skills/cortexdb/SKILL.md: 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.
  • .agents/skills/cortexdb/SKILL.md: An agent's record of its own run, as graph records: `StartRun`, `BeginStep` / `EndStep` (a step is written as running, with `TRIGGERED` edges from the steps it consumed, before its work runs), `RecordStep`, `FinishRun`;
  • .agents/skills/cortexdb/SKILL.md: read back with `GetRun`, `ListRuns`, `RunSteps`, `SummarizeRun`, `StepLineage` and `ReplayRun` (the run as of any instant).
  • .agents/skills/cortexdb/SKILL.md: go run ./examples/01_core
  • .agents/skills/cortexdb/SKILL.md: go run ./examples/02_rag
  • .agents/skills/cortexdb/SKILL.md: go run ./examples/03_memoryflow
  • .agents/skills/cortexdb/SKILL.md: go run ./examples/04_knowledge_graph
  • .agents/skills/cortexdb/SKILL.md: go run ./examples/05_graphflow
  • .agents/skills/cortexdb/SKILL.md: go run ./examples/06_tools_mcp
  • .agents/skills/cortexdb/SKILL.md: When changing CortexDB, run:
  • SKILL.md: | Scenario | Start with | What it really does | | --- | --- | --- | | Store vectors, FTS5, or run simple TopK retrieval | `pkg/cortexdb` `Quick()`;
  • SKILL.md: | | Import external CSV or MySQL/PG SQL dumps into RAG + knowledge graph | `pkg/importflow` `New().Run()` / `AutoImport()` | Parses a source into records, routes columns via a `MappingPlan` to RAG content and KG entities/relations, with optional AI mapping inference and triple extraction.
  • SKILL.md: Codebase knowledge graph: `graphflow.Pipeline.Run`
  • SKILL.md: Run with `GOMEMLIMIT` set below the device's memory so the garbage collector works before the kernel does.
  • SKILL.md: `PostgresStore` satisfies the same `BrainStore` contract as `SQLiteStore`: vectors, hybrid search, memory, RDF graph, SPARQL, ontology and the tool surface all run on either.
  • SKILL.md: without it the run skips them, naming what is uncovered (`pkg/connector`'s source/CDC tests take their own `CONNECTOR_PG_DSN` / `CONNECTOR_PG_REPL_DSN` / `CONNECTOR_MYSQL_*`).
  • SKILL.md: past it the document is left out of every search, chunk tool, graph walk and aggregate, and `sweep_expired` / `cortexdb-mcp-stdio --sweep-expired [--dry-run]` deletes expired documents and memories.
  • SKILL.md: re-run the rules after a manual full refresh, which clears them.
  • SKILL.md: 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.
  • SKILL.md: // Which nodes those edges run through — what is wrong.
  • SKILL.md: 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 th …[+67 chars]
  • SKILL.md: run, _ := db.StartRun(ctx, cortexdb.RunStart{Task: "checkout p99 alert", Agent: "devops-agent"})
  • SKILL.md: plan, _ := db.RecordStep(ctx, cortexdb.StepStart{RunID: run.ID, Kind: cortexdb.StepKindLLMCall, Name: "plan"},
  • SKILL.md: st, _ := db.BeginStep(ctx, cortexdb.StepStart{RunID: run.ID, Kind: cortexdb.StepKindToolCall, Name: "restart_pool", Parents: []string{plan.ID}})
  • SKILL.md: _, _ = db.FinishRun(ctx, run.ID, cortexdb.RunEnd{Outcome: "resolved"})
  • SKILL.md: sum, _ := db.SummarizeRun(ctx, run.ID) // tokens, cost, open/failed steps, critical path, least confident step
  • SKILL.md: then, _ := db.ReplayRun(ctx, run.ID, someInstant) // the run as it stood then, from history
  • SKILL.md: 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.
  • SKILL.md: a run finishes once.
  • SKILL.md: // Dry run first; with neither rule_ids nor rules, every enabled rule runs.
  • SKILL.md: rep, _ := im.Run(ctx, src, plan) // rep.RowsRead/ChunksIndexed/TriplesCreated/UnparsedStatements
  • SKILL.md: With an inferer, `im.AutoImport(ctx, src, importflow.Goal{BuildRAG: true, BuildKG: true})` does plan + run in one step.
  • SKILL.md: Review the plan, then feed it to `im.Run` / the connector to build the graph.
  • SKILL.md: plan.Sign("you", time.Now()) // Run refuses an unsigned plan
  • SKILL.md: rep, _ := importflow.New(db).Run(ctx, connector.Desensitized(src, d), mapping)
  • SKILL.md: **Library API only** — `w.Run(ctx)` does one pass and the caller schedules it (loop / cron).
  • SKILL.md: _ = w.Run(ctx) // schedule on an interval; resumes from the checkpoint
  • SKILL.md: **Route B-PG (Postgres logical replication, `NewPostgresCDCSource`):** a true CDC source over `pgoutput` that **captures hard deletes** and **streams continuously** — `w.Run(ctx)` blocks until ctx is cancelled and resumes by LSN from the checkpoint (`Checkpoint.Position`).
  • SKILL.md: go w.Run(ctx) // streams insert/update/delete continuously; resumes by LSN
  • SKILL.md: Like Route B-PG it **captures hard deletes** and **streams continuously** — `w.Run(ctx)` blocks until ctx is cancelled and resumes by binlog position (`Checkpoint.Position`).
  • SKILL.md: go w.Run(ctx) // streams insert/update/delete; resumes by binlog position
  • SKILL.md: Wire via `connector.NewMCPServer(tb, opts)` / `connector.RunMCPStdio(ctx, tb, opts)`, `connector.RegisterMCPTools(server, tb)` to ride another server, or run `cmd/cortexdb-connector-mcp`.
  • SKILL.md: Transport is plaintext by design — run it over loopback, a trusted LAN, or Tailscale, or publish it as `https://host` behind a TLS-terminating proxy (`CORTEXDB_REMOTE=https://host`;
  • SKILL.md: the latter two need direct database access, so they run where the database lives.
  • SKILL.md: From a shell: `cortexdb-mcp --import-agent-memory [--sessions] [--since 30d] [--max N] [--dry-run]`.
  • SKILL.md: With an active ontology, a capture is told its object types: the active schema is read once per run (on a shared brain through `ontology_list`), each declared type's `api_name`, a one-line description and its aliases are listed in the prompt — at most 60 types, 160-character descriptio …[+152 chars]
  • SKILL.md: graphflow's `LLMExtractor` does the same under `Pipeline.Run` (undeclared → `graphflow_node`).
  • SKILL.md: Python — `clients/python/` (PyPI): `pip install cortexdb-client`;
  • SKILL.md: Node — `clients/node/` (npm): `npm install cortexdb-client`;
  • SKILL.md: Published to ClawHub (`clawhub skill install cortexdb-agent-memory`) and installable from git / skills.sh (`hermes skills install git:liliang-cn/cortexdb@main`, `npx skills add liliang-cn/cortexdb`).
  • SKILL.md: go run ./examples/01_core
  • SKILL.md: go run ./examples/02_rag
  • SKILL.md: go run ./examples/03_memoryflow
  • SKILL.md: go run ./examples/04_knowledge_graph
  • SKILL.md: go run ./examples/05_graphflow
  • SKILL.md: go run ./examples/06_tools_mcp
  • SKILL.md: go run ./examples/07_importflow
  • SKILL.md: go run ./examples/08_self_knowledge_graph # docs -> graphflow -> KG of this project; qa_test.go answers from graph edges
  • SKILL.md: go run ./examples/16_ontology # typed object types, actions, object sets, typed tools, schema diff
  • SKILL.md: When changing CortexDB, run:
  • plugins/cortexdb/skills/cortexdb/SKILL.md: Run with `GOMEMLIMIT` set below the device's memory so the garbage collector works before the kernel does.
  • plugins/cortexdb/skills/cortexdb/SKILL.md: 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.
  • plugins/cortexdb/skills/cortexdb/SKILL.md: From a shell: `cortexdb-mcp --import-agent-memory [--sessions] [--since 30d] [--max N] [--dry-run]`.
  • plugins/cortexdb/skills/cortexdb/SKILL.md: re-run the rules after a manual full refresh, which clears them.
  • plugins/cortexdb/skills/cortexdb/SKILL.md: 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.
  • plugins/cortexdb/skills/cortexdb/SKILL.md: An agent's record of its own run, as graph records: `StartRun`, `BeginStep` / `EndStep` (a step is written as running, with `TRIGGERED` edges from the steps it consumed, before its work runs), `RecordStep`, `FinishRun`;
  • plugins/cortexdb/skills/cortexdb/SKILL.md: read back with `GetRun`, `ListRuns`, `RunSteps`, `SummarizeRun`, `StepLineage` and `ReplayRun` (the run as of any instant).
  • plugins/cortexdb/skills/cortexdb/SKILL.md: Wire via `connector.NewToolbox(db, opts)` + `connector.NewMCPServer(tb, opts)` / `connector.RunMCPStdio(ctx, tb, opts)`, `connector.RegisterMCPTools(server, tb)` to ride another server, or run `cmd/cortexdb-connector-mcp`.
  • plugins/cortexdb/skills/cortexdb/SKILL.md: go run ./examples/01_core
  • plugins/cortexdb/skills/cortexdb/SKILL.md: go run ./examples/02_rag
  • plugins/cortexdb/skills/cortexdb/SKILL.md: go run ./examples/03_memoryflow
  • plugins/cortexdb/skills/cortexdb/SKILL.md: go run ./examples/04_knowledge_graph
  • plugins/cortexdb/skills/cortexdb/SKILL.md: go run ./examples/05_graphflow
  • plugins/cortexdb/skills/cortexdb/SKILL.md: go run ./examples/06_tools_mcp
  • plugins/cortexdb/skills/cortexdb/SKILL.md: When changing CortexDB, run:
  • skills/cortexdb-memory-hermes/SKILL.md: # install the binary (or download a prebuilt release)
  • skills/cortexdb-memory-hermes/SKILL.md: go install github.com/liliang-cn/cortexdb/v2/cmd/cortexdb-grpc@latest
  • skills/cortexdb-memory-hermes/SKILL.md: For automatic pre-turn recall and completed-turn synchronization, install the native Hermes `MemoryProvider` at `plugins/hermes-cortexdb-memory` and set `memory.provider: cortexdb`.
  • skills/cortexdb-memory-hermes/SKILL.md: Hermes also speaks MCP — if you prefer, run `cortexdb-mcp-stdio` and connect it as an MCP server instead of (or alongside) this skill.
  • skills/cortexdb-memory-openclaw/SKILL.md: # install the binary (or download a prebuilt release)
  • skills/cortexdb-memory-openclaw/SKILL.md: go install github.com/liliang-cn/cortexdb/v2/cmd/cortexdb-grpc@latest
  • skills/cortexdb-memory-openclaw/SKILL.md: For automatic OpenClaw memory lifecycle integration, install the native plugin at `plugins/openclaw-cortexdb-memory` and select `cortexdb-memory` in `plugins.slots.memory`.

MCP servers (1)

  • plugins/cortexdb/.mcp.json (cortexdb): ${CLAUDE_PLUGIN_ROOT}/bin/cortexdb-mcp

Hooks (4)

  • plugins/cortexdb/hooks/hooks.json (SessionStart): ${CLAUDE_PLUGIN_ROOT}/bin/cortexdb-session-start
  • plugins/cortexdb/hooks/hooks.json (UserPromptSubmit): ${CLAUDE_PLUGIN_ROOT}/bin/cortexdb-recall
  • plugins/cortexdb/hooks/hooks.json (PreToolUse): ${CLAUDE_PLUGIN_ROOT}/bin/cortexdb-file-context
  • plugins/cortexdb/hooks/hooks.json (SessionEnd): ${CLAUDE_PLUGIN_ROOT}/bin/cortexdb-session-end
  • Medium risk: exfil-endpoint (.agents/skills/cortexdb/SKILL.md:301)
  • Medium risk: exfil-endpoint (plugins/cortexdb/skills/cortexdb/SKILL.md:308)
  • Low risk: network-instructions (SKILL.md:1379)
  • Low risk: network-instructions (skills/cortexdb-memory-hermes/SKILL.md:49)

Attribution and licence

First committed by
GitHub avatar of liliang-cnliliang-cn
Publisher
Liang Li (Community)
Source
liliang-cn/cortexdb · commit d39714c
Licence
MIT License (files served here)
  • ATTRIBUTION.md (written by AutoGineer)
Synced
Contributors
liliang-cn, lfoletti

AutoGineer is not affiliated with or endorsed by liliang-cn.

Install from source

501 of its files are not served here, so there is no ZIP. liliang-cn/cortexdb at d39714c