CortexDB
AI memory and a knowledge graph in one SQLite file. Pure Go, no service to run, works without an embedding model.
Install
| |
|---|
| Go library | go get github.com/liliang-cn/cortexdb/v2 |
| Claude Code | /plugin marketplace add liliang-cn/cortexdb, then /plugin install cortexdb@cortexdb |
| Codex | codex plugin marketplace add liliang-cn/cortexdb && codex plugin add cortexdb@cortexdb |
| Claude Code mod (optional) | /plugin install cortexdb-live@cortexdb |
| DeepSeek Harness | dsh plugin --profile web add "github:liliang-cn/cortexdb#semver:^2&path:/plugins/dsh-cortexdb-memory" (guide) |
| Obsidian | unzip a release's cortexdb-obsidian.zip into <vault>/.obsidian/plugins/ (guide) |
| Shared-brain server | go install github.com/liliang-cn/cortexdb/v2/cmd/cortexdb-grpc@latest |
| Clients | cargo 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.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
