README
¶
Exocortex
Foundation-shaped memory kernel for the Misty Step agent fleet: one binary that gives every agent a uniform read/write/search interface over registered knowledge corpora.
Status: v0.2 on master. Built in Go with sole-publisher isolation,
fail-closed reads, compare-and-swap concurrency, hybrid semantic retrieval,
and executive orientation briefs (brief). The CLI and bundled skill
(skill://exocortex) is the universal fleet baseline.
Model
- Cortex — a writable markdown+git corpus registered with the kernel. Daybook is the first. Full read/write/search/lint/lineage over plain files humans can still read and diff.
- Feed — an adapter that ingests a foreign source (Notion, Google Drive,
harness session logs) into a cortex as compiled, provenance-stamped notes
with
source:lineage. Raw sources stay where they are.
Surface
exocortex register daybook ~/Development/misty-step/daybook
exocortex brief "<topic>" # executive orientation briefing
exocortex search "<query>" [--mode hybrid|bm25|vector] [--type decision|memo|session] # omitted mode is hybrid; pass bm25 for deterministic
exocortex get <path> # read from committed Git HEAD snapshot
exocortex note "<thought>" # atomic memo capture (~2s)
exocortex put <path> --from draft.md # create-only (fails if path exists)
exocortex put <path> --from draft.md --expects <sha> # update: stored-revision hash REQUIRED
exocortex log <path> # git lineage
exocortex lint [<path>] # frontmatter floor gate
exocortex sync [--cortex <name>] # refresh QMD index and embeddings
exocortex status [--cortex <name>] # dirty markers, last sync, last error
Develop
Clone-to-green:
./scripts/check.sh
That is the owned gate: gofmt, go vet, golangci-lint fuse (cyclop ≤ 15,
staticcheck, production errcheck, gocognit < 16, nestif < 5), gitleaks,
govulncheck, module token budgets, go test -race, and a CLI smoke
(register → put → get → lint on a temp cortex). scripts/lint-report.sh
prints remaining gocognit/nestif bands plus funlen, maintidx, and dupl without failing.
Go 1.26.6 is required (go.mod); 1.26.5 stdlib is govulncheck-red.
Install the binary so go version -m names this module:
go install -trimpath ./cmd/exocortex
The user timer runs ~/.local/bin/exocortex. Rebuild after merge. Roll
back by installing the previous commit the same way.
./scripts/install-hooks.sh # core.hooksPath=.githooks
Docs
- SPEC.md — full design: decisions, contracts, delivery plan
- VISION.md — why this exists
- ADR-0001 — accepted kernel decision
- skills/exocortex/SKILL.md — bundled agent skill
(source;
scripts/install-skill.shwrites omp-config; omp-config./installdeploys live)
Clone-to-green: go test ./.... Generate the omp-config copy with
scripts/install-skill.sh <omp-config>/skills/exocortex. Deploy live with
omp-config ./install. Drift fails skills/exocortex/check-source.sh in omp-config.
Provenance
This repo previously hosted an earlier, unrelated "evidence core" concept
(citable context packets, 2026-07). On 2026-08-21 the operator repurposed the
repository for the memory kernel. The prior tree remains recoverable from git
history; LICENSE was retained.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
exocortex
command
|
|
|
internal
|
|
|
cli
Package cli wires the exocortex command surface.
|
Package cli wires the exocortex command surface. |
|
fm
Package frontmatter parses, validates, and surgically edits markdown+YAML frontmatter notes.
|
Package frontmatter parses, validates, and surgically edits markdown+YAML frontmatter notes. |
|
kernel
Package kernel implements the exocortex memory-kernel operations over registered cortices: registry management, path resolution, and the read/write/search/lint surface shared by the CLI and MCP faces.
|
Package kernel implements the exocortex memory-kernel operations over registered cortices: registry management, path resolution, and the read/write/search/lint surface shared by the CLI and MCP faces. |
|
mcp
Package mcp exposes the kernel operations as an MCP stdio server — the second face of the same binary (SPEC: CLI and MCP from one implementation).
|
Package mcp exposes the kernel operations as an MCP stdio server — the second face of the same binary (SPEC: CLI and MCP from one implementation). |
|
okf
Package okf validates the optional OKF v0.2 metadata families — trust/lifecycle events, stale_after, and provenance — against the structural rules of the Open Knowledge Format v0.2 spec (SPEC §5, §10).
|
Package okf validates the optional OKF v0.2 metadata families — trust/lifecycle events, stale_after, and provenance — against the structural rules of the Open Knowledge Format v0.2 spec (SPEC §5, §10). |
|
orient
Package orient classifies search hits for --type and brief.
|
Package orient classifies search hits for --type and brief. |
|
qmd
Package qmd shells out to the local QMD CLI for retrieval.
|
Package qmd shells out to the local QMD CLI for retrieval. |
|
registry
Package registry loads user and directory-scoped cortex declarations.
|
Package registry loads user and directory-scoped cortex declarations. |
|
skillsrc
Package skillsrc locates the bundled Exocortex skill and compares generated copies to it.
|
Package skillsrc locates the bundled Exocortex skill and compares generated copies to it. |