cortexes

A personal knowledge vault plugin for Claude Code — session recording, memory distillation, semantic retrieval.

English · 繁體中文

What It Does

Cortexes turns your working memory into a searchable knowledge base. Every Claude Code session gets automatically recorded when it ends, then can be distilled and retrieved later.

• Automatic capture — a full report (commits, findings, decisions) is generated when a session ends and saved to the vault
• Semantic search — OpenAI embeddings + ChromaDB, with mixed Chinese/English query support
• Knowledge distillation — extracts hard-won lessons, internal conventions, and key decisions from raw session dumps
• Memory injection — detects the current repo at session start and offers to load related memory

Design philosophy: the vault is the source of truth (plain markdown + git); the vector store is just a rebuildable derived index.

Quick Start

1. Install the plugin

# Add the marketplace, then install the plugin from it
/plugin marketplace add https://github.com/XBlueSky/cortexes.git#plugin
/plugin install cortexes@cortex

The marketplace is named cortex and the plugin inside it is cortexes — hence cortexes@cortex. The marketplace name is kept from 1.x on purpose so that existing marketplace add registrations keep working.

2. Install the cortex-vec CLI

The CLI is published on PyPI as cortex-vec:

# Recommended: isolated tool install via uv
uv tool install cortex-vec

# Or with pip
pip install cortex-vec

Upgrade with uv tool upgrade cortex-vec (or pip install -U cortex-vec) after a plugin update. /cortexes:genesis checks for the CLI and offers this install when it is missing. To run the unreleased development version instead, install from the repo:

uv tool install "git+https://github.com/XBlueSky/cortexes.git@plugin#subdirectory=cortex-vec"

OPENAI_API_KEY is optional. Setting it enables embeddings, and with them semantic (vector) search. Without it nothing breaks: search runs on the local BM25 index, entirely on your machine and with nothing sent to OpenAI — see Environment Variables.

3. Initialize

/cortexes:genesis /path/to/your/vault

This sets the vault path and author info, and builds the semantic index.

4. Start using it

"save to cortex"     → manually save knowledge
"check cortex"       → semantic search over the vault
"distill"            → extract knowledge from Raw/
"broadcast"          → fuse new Raw content into existing pages

Upgrading from 1.x to 2.0

2.0.0 renames the plugin from cortex to cortexes. Your vault, config and indexes are untouched — there is no data migration.

1. Update the marketplace. In Claude Code run /plugin marketplace update cortex (or remove and re-add it).

2. Start a new session. The marketplace manifest ships a renames mapping (cortex → cortexes), so the rename is carried for you: the update re-points your enabled plugin at cortexes@cortex, and the next session start materializes it at 2.0.0. You do not need to uninstall and reinstall. In between the two steps /plugin may still list the old cortex row annotated Renamed to "cortexes" in the "cortex" marketplace — that is the migration staged, not an error. If you ever do reinstall from scratch, the id is /plugin install cortexes@cortex.

3. Use the new command prefix. /cortex:* no longer resolves; every command moved to /cortexes:* (/cortexes:genesis, /cortexes:evolve, /cortexes:distill, /cortexes:query, /cortexes:broadcast, /cortexes:takeoff). Natural-language triggers are unchanged — "存到 cortex" and "查 cortex" still work.

4. If your vault has a Weekly/ directory, move what you still want. Weekly/ is no longer part of the vault taxonomy: 2.0 does not create it, index it, search it, or list it. It was already unreachable — the weekly report skill went in 0.22.0 and Weekly/ left the index back in 0.5.0 — so this changes nothing about what you can find. Cortexes will not move, rewrite, or delete an existing Weekly/; copy anything still worth keeping into Notes/ or Projects/ yourself, at your own pace, and whatever you leave stays where it is.

5. Upgrade the CLI too.

   uv tool upgrade cortex-vec    # or: pip install -U cortex-vec
   

   cortex-vec 0.10.0 is the version this plugin release ships against. 0.8.0 is what carried the Weekly removal into the CLI — --type weekly is gone from search --help and Weekly/ is no longer classified as a content type — 0.9.0 adds the cosine backfill and the retrieval-filter fixes that 2.1.0's dedup and scoped search depend on, and 0.10.0 adds the quiet stderr and classified exit codes the 2.2.0 query skill reads. Older CLIs keep working, but a scoped search on one still leaks out-of-scope pages and a keyword-only hit still reports 0.00.

6. Nothing else changes. ~/.cortex/config.json, the vector/BM25 indexes and caches, and the CORTEX_* environment variables all keep their names and paths. No rebuild, no re-index, no config edit.

Website

Live docs and changelog: https://cortexes.pages.dev (Cloudflare Pages, generated from .cc-marketspec/dist/manifest.json). See site/README.md for local builds.

Commands & Skills

Commands

Command	Description
/cortexes:genesis	Initialize the vault — set path, author, rebuild the index
/cortexes:evolve	Manually save knowledge to Notes or Projects (also writes log.md)
/cortexes:distill	Distill Raw/ session records into Notes/Projects (map-first navigation + two-stage evaluation + pending-merge exit)
/cortexes:query	Search the vault — semantic (cortex-vec) with grep and BM25 fallbacks. Running it counts as an explicit request, so it searches even when the session opted out
/cortexes:broadcast	Fuse newly distilled content into related existing pages (llm-wiki-style ingest)
/cortexes:takeoff	Hand-off batons — curate temporary, non-git hand-offs for a later session to resume, one per work line ([topic] / resume [topic] / done [topic] subcommands)

Skills (auto-triggered)

Skill	Trigger
cortex-evolve	"save to cortex", "note this down", "remember this"
cortex-distill	"distill", "clean up raw", "distill raw records"
cortex-broadcast	"broadcast", "merge pending-merge", "fuse this into the vault"
cortex-takeoff	"hand off", "takeoff", "hand off to next session", "context is running low"
cortex-query	"check cortex", "have I noted this before", "is this in cortex"

Hooks

Hook	Event	Behavior
Session Report	SessionEnd	On session end, filters the transcript through a TOML pipeline before writing to Raw/
Memory Injection	SessionStart	Interactive menu — checks vault backlog status and asks what to do next
Deck	hooks module (hooks/deck.tsx)	Draws the SessionStart menu as a band above the prompt (digits 1–9 press its buttons) and offers a takeoff hand-off once per context window at 70% use. Without the module the model shows the text menu as before

Recording is automatic. Every session over 4 KB is written to your vault when it ends — there is no per-session prompt. Set CORTEX_SKIP_RECORD=1 to skip a session, and see PRIVACY.md for exactly what is captured, what is excluded, and what (if anything) leaves your machine.

Transcript Filter (0.9.0+)

Before writing to Raw/, the SessionEnd hook runs a TOML-driven filter pipeline that strips tool output with no knowledge value (e.g. ls, volume listings, repetitive build logs) — you can write custom filters per slash command so what lands in Raw/ actually carries signal.

Architecture

cortex repo
├── plugin branch (orphan)     ← the Claude Code plugin (this file lives here)
└── main branch                ← Obsidian vault data

~/.cortex/
├── config.json                ← settings produced by genesis
└── vectorstore/                ← ChromaDB semantic index (local only, not in git)

Vault Structure

Raw/YYYY/MM/DD/                ← session dumps (complete, distilled on demand)
Notes/<category>/              ← distilled technical knowledge
Projects/<repo-name>/          ← project notes organized by repo
_index.md                      ← vault-wide summary index
log.md                         ← chronological history of evolve/distill

Nothing machine-checks _index.md for consistency (reorganizing pages is the one path that changes the index with no skill involved). See docs/index-audit.md for the audit, and for the regex traps that let a naive check pass while reporting the wrong set.

Data Flow

Every session:
  SessionStart → surfaces available memory → user decides whether to load it
  ...work happens...
  session ends → SessionEnd hook → filter → Raw/   (automatic, no prompt)

Anytime:
  /cortexes:evolve    → Notes/Projects + _index.md + log.md + vector store
  /cortexes:query     → vector search → precise file reads

Periodically:
  /cortexes:distill   → Raw → Notes/Projects (+ pending-merge → broadcast)
  /cortexes:broadcast → pending-merge → fused into existing Notes/Projects

Retrieval Strategy

Hybrid retrieval (0.4.0+) — BM25 + vector dual streams, fused with Reciprocal Rank Fusion (RRF, k=60), default weights w_bm25=0.4 / w_vec=0.6:

• BM25 stream — exact lexical matching (function names, repo names, issue IDs), with jieba CJK segmentation for mixed Chinese/English queries. The index persists at ~/.cortex/bm25/, kept in sync with ChromaDB by rebuild/upsert/delete.
• Vector stream — OpenAI text-embedding-3-small semantic search, dual-vector (document body + bilingual summary), covering cases that are semantically close but lexically different.
• Degradation strategy — without OPENAI_API_KEY, or offline, this automatically falls back to BM25-only, with no dependency on the skill-layer grep fallback.

Other layers:

1. Raw search (on demand) — only queries original session records when tracing history

cortex-vec CLI

The vault's semantic indexing tool, built on ChromaDB + OpenAI text-embedding-3-small, paired with gpt-5.4-mini to generate a bilingual summary as a second embedding (dual-vector) to improve recall for mixed Chinese/English queries.

cortex-vec status                          # view index status
cortex-vec rebuild                         # full index rebuild
cortex-vec search "nginx certificate"      # semantic search
cortex-vec search "oauth" --repo acme-core # filter by repo (narrows Projects/ only; Notes/ always pass)
cortex-vec search "sharing" --type project # filter by type
cortex-vec upsert Notes/Nginx/new.md       # add/update a single document
cortex-vec delete Notes/Nginx/old.md       # delete a document

Hybrid Retrieval (0.4.0+)