CORTEXTA is a local-first cognitive runtime for software teams that want durable, queryable project memory. It ingests repositories and chat history, compacts large payloads into deterministic envelopes, resurrects content on demand, and compiles relevance-ranked context for coding agents and developer tooling.
██████╗ ██████╗ ██████╗ ████████╗███████╗██╗ ██╗ █████╗ ██╔════╝██╔═══██╗██╔══██╗╚══██╔══╝██╔════╝╚██╗██╔╝██╔══██╗ ██║ ██║ ██║██████╔╝ ██║ █████╗ ╚███╔╝ ███████║ ██║ ██║ ██║██╔══██╗ ██║ ██╔══╝ ██╔██╗ ██╔══██║ ╚██████╗╚██████╔╝██║ ██║ ██║ ███████╗██╔╝ ██╗██║ ██║ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝ ╚══════╝╚═╝ ╚═╝╚═╝ ╚═╝ CORTEXA CLI Local-first memory runtime for your dev workflow. ────────────────────────────────────────────────────────────────────────────────────── Quick start $ pnpm run cortexa -- init $ pnpm run cortexa -- ingest . projectId auto-inferred from folder name (override with --project-id=<id>) $ pnpm run cortexa -- query "how did we solve retry jitter?" $ pnpm run cortexa -- context "prepare implementation plan" $ pnpm run cortexa -- llm status $ pnpm run cortexa -- agents list $ pnpm run cortexa -- evolve "upgrade progression telemetry" --project-id=my-project --dry-run Core commands init Initialize SQLite schema and vector collection. ingest [path] [options] Ingest code and optional chats; projectId auto-inferred unless overridden. llm <status|train|preview> [options] Train/use the quantized local mini LLM for agent-memory workflows. query <text> Run hybrid retrieval over memories. context <text> Compile a token-bounded context payload. agents <list|run> [options] List/run Cortexa agents and multi-agent loops. evolve <text> [options] Run progression evolution and emit stage telemetry. daemon <start|stop|status> Control local daemon API runtime. Memory commands memory list [projectId] [--limit=<n>] List recent memories. memory search <query> [--project-id=<id>] Search memory store with scoring. memory get <id> [--full] Show memory content. memory resurrect <id> [--full] Read restored compact content. memory delete <id> Delete one memory item. memory stats [--project-id=<id>] Compaction and integrity stats. memory opportunities [--project-id=<id>] Top estimated compaction savings from plain rows. memory audit [--project-id=<id>] [--limit=<n>] Resurrection integrity audit + repair guidance. memory backfill [--apply] [--limit=<n>] Dry-run/apply compaction backfill. memory dashboard [options] Compaction dashboard payload/report. Aliases + help dashboard [options] Alias of: memory dashboard [options]. help | -h | --help Show this home screen. ────────────────────────────────────────────────────────────────────────────────────── Tip: use -- after pnpm script invocation, e.g. pnpm run cortexa -- dashboard --json --out-json=./tmp/dashboard.json
Diagnostic payloads, runtime health hints, and a CLI status surface for faster triage.
Deterministic include/exclude and redaction rules, applied before memories are stored.
Live suggestions stay active when compiled context exists, even if no stored memories were used.
Quantized local model training, preview, and schema-aware completions for lightweight workflows.
A local-first cognitive runtime that transforms how developers manage, retrieve, and utilize institutional knowledge across projects.
Hybrid storage combines SQLite metadata with vector indexes (Qdrant, Chroma, or in-memory). Code snippets, design notes, and chat transcripts become searchable memory units with stable, project-scoped identity.
Memory units are compacted with Brotli into deterministic envelopes. Content is resurrected at read time, reducing storage footprint while preserving checksums, previews, and operational recoverability.
Combines vector similarity with lexical ranking to surface the most relevant context. Token-bounded context compilation controls prompt size for coding assistants and CLI workflows that require concise, trustworthy context.
The daemon exposes HTTP and WebSocket endpoints for query, context compilation, evolution tracking, and compaction operations, enabling integration with editors, agents, and CI tools.
Persistent trend snapshots and per-project anomaly reporting expose integrity issues such as invalid checksums and decode errors, making maintenance predictable over long-running projects.
Your code and conversations never leave your machine unless you choose. Full control over vector backends, embedding services, data paths, and daemon exposure boundaries.
Recent operator-facing additions, stability fixes, and UX polish. Full details are available in the CHANGELOG, on the GitHub release page, and in the commit trail below.
Added runtime LLM diagnostics surfaced via POST /cxlink/llm/status and the CLI
cortexa llm status --runtime. Operators can now see effective mode, timeout,
reachable state, last success/error and diagnostic hints for faster root cause analysis.
pnpm run cortexa -- llm status --runtime
curl -s -X POST http://localhost:4312/cxlink/llm/status \
-H "content-type: application/json" \
-d '{"projectId":"my-project"}'Project-level ingestion via cortexa.policy.json is supported: include/exclude globs,
language filters, redaction rules and size limits. The ingestion pipeline applies policy-driven
filtering and redaction before persisting memories.
pnpm run cortexa -- ingest . --policy-check
pnpm run cortexa -- ingest . --policy=.\cortexa.policy.json --max-files=25Improved live context streaming: suggestions are no longer suppressed when compiled context text
exists but stored memory counts are zero (useful during inline/ephemeral compilations). This
resolves a test-time suppression that prevented valid contextDeltaSuggested events.
pnpm run test:context-stream
# optional live check
pnpm run cortexa -- daemon startcontextDeltaSuggested when compiled context exists.Quantized local mini-LLM support for compact n-gram inference and JSON schema completions. CLI
surface expanded with llm train, llm preview, and improved
llm status outputs.
pnpm run cortexa -- llm train . --project-id=my-project --max-vocab=4096
pnpm run cortexa -- llm preview "summarize the release" --max-tokens=96Modular, layered design separating CLI concerns from the core memory engine.
How raw source files and chat transcripts become searchable memory units.
How a compact envelope is verified, decoded, and assembled into a prompt-ready context block.
invalidChecksum)
or Brotli decode throws (decodeError),
the anomaly is recorded in the compaction analytics dashboard and the memory unit is flagged
for backfill. The preview text is served as a fallback, and context compilation continues
with remaining healthy units.
-- delimiter support43124321From ingestion to retrieval — the complete lifecycle of a memory unit in CORTEXTA.
Codebases and chat histories are parsed, chunked, and enriched with AST-derived hints. Each unit receives metadata tags, project IDs, and embedding vectors before entering the memory store.
Memory units are persisted in SQLite with full metadata. Vector embeddings are indexed via Qdrant, Chroma, or an in-memory fallback. The system maintains referential integrity between lexical and semantic indexes.
Large memory payloads are compressed into compact envelopes using Brotli. The envelope format
cortexa://mem/compact/v1/
preserves preview text and checksums. Original content is replaced by the compact envelope
to save space.
When a memory unit is retrieved, the compaction layer deterministically resurrects the
original content from its envelope. Integrity is verified via checksum. Anomalies (invalidChecksum,
decodeError)
are tracked for dashboard reporting.
User queries trigger hybrid retrieval — combining vector similarity scores with lexical matching. Results are ranked by relevance and filtered by project scope, minimum score thresholds, and top-k limits.
Retrieved memories are packed into a token-bounded context payload. Copilot-friendly summaries reduce token cost while preserving semantic meaning. The result is a prompt-ready context block for any coding agent.
Source code & chat logs
Brotli + br64 encoding
SQLite + vector index
Original content restored
Where Cortexta creates immediate leverage for real development teams.
Keep architectural decisions, implementation details, and debugging trails available across days or weeks, even when context switching between projects.
Transfer project memory between teammates with queryable provenance, reducing repeated explanations and preserving the rationale behind key changes.
Search historical fixes, recovery steps, and environment constraints to accelerate incident diagnosis and strengthen prevention playbooks.
Feed planners, writers, and refactor agents with compact, ranked context so each step starts from shared memory instead of repeated prompt priming.
A practical scorecard based on architecture depth, operational design, and developer usability.
Clear layering across CLI, core engine, storage, and daemon interfaces.
Strong command surface and observability, with room for guided onboarding presets.
Compaction analytics and anomaly tracking are strong and improving release by release.
Efficient compaction and bounded context packing align well with local-first constraints.
Good local-first boundaries and daemon token support; policy hardening can extend further.
Overall grade: A- — a robust foundation for long-lived developer memory, with the highest upside in standardized secure defaults and larger-scale team onboarding paths.
A concrete, field-friendly flow for turning raw repositories into durable team intelligence.
A realistic onboarding arc you can run on day one of a legacy service takeover.
Establish memory substrateInitialize local persistence and vector setup
with
pnpm run cortexa -- init.
Ingest repo + historical chatRun ingestion with explicit project scope to preserve lineage across future branches and incident threads.
Probe semantic coverageIssue targeted queries (auth, retries, migrations, rollbacks) and inspect whether retrieved evidence reflects true implementation intent.
Compile agent-ready contextGenerate prompt-bounded bundles via
context so automation begins from project memory instead of prompt
guesswork.
Lock in maintenance rhythmSchedule periodic memory audit
and
dry-run memory backfill to keep compaction healthy over long-lived
projects.
A lightweight control table for deciding whether to keep, repair, or escalate memory operations.
| Moment | Check | Signal | Action |
|---|---|---|---|
| Coverage drift | memory search |
Low-recall answers for known topics | Re-ingest recent diffs + chats for missing feature slices. |
| Integrity alert | memory audit |
invalidChecksum / decodeError detected | Queue backfill and review high-impact items first. |
| Prompt overflow | context |
Token budget clipping critical rationale | Tighten top-k, raise score floor, rerun context compile. |
| Incident mode | query |
Multiple plausible but conflicting fixes | Prioritize newest + highest score, then attach provenance trail. |
Optimize for continuity and fast recall between intense deep-work sessions and context switches.
Optimize for onboarding velocity and cross-branch memory consistency across rotating contributors.
Optimize for evidence clarity under pressure, ensuring rollback and mitigation memory are instantly retrievable.
Key architectural views, data flows, and operational patterns.
The cortexa
command is the single entry point for all operations.
Initialize SQLite schema and vector collection bootstrap.
Ingest code and chat sessions into the memory store.
Hybrid memory retrieval with natural language queries.
Compile a prompt-ready context payload for coding agents.
Memory operations: list, search, get, resurrect, delete, stats, backfill, dashboard.
Manage the local HTTP + WebSocket daemon runtime.
Inspect and operate the local quantized mini-LLM workflow.
List available agents and run progression-aware memory evolution loops.
Environment variables for storage, vector backends, compaction, and daemon behavior.
| Variable | Default | Description |
|---|---|---|
| CORTEXA_DB_PATH | data/cortexa.db | SQLite database file path |
| CORTEXA_VECTOR_PROVIDER | qdrant | Vector backend: qdrant
| chroma
| memory
|
| CORTEXA_VECTOR_URL | http://localhost:6333 | Qdrant endpoint URL |
| CORTEXA_CHROMA_URL | http://localhost:8001 | Chroma endpoint URL |
| CORTEXA_EMBEDDING_URL | — | Optional external embedding service |
| CORTEXA_INGEST_MAX_FILE_BYTES | 786432 | Maximum file size for ingestion (768 KB) |
| CORTEXA_DAEMON_PORT | 4312 | HTTP daemon port |
| CORTEXA_WS_PORT | 4321 | WebSocket port |
| CORTEXA_DAEMON_TOKEN | — | Authentication token for daemon |
| CORTEXA_DAEMON_BODY_LIMIT | 6mb | Max request body size |
| CORTEXA_DAEMON_AUTOSTART | 1 | Set to 0
to disable daemon module auto-start. |
| CORTEXA_LLM_MODE | mini-local | LLM operation mode. Use off
or disabled
to bypass local generation. |
| CORTEXA_LLM_MODEL_PATH | data/llm/cortexa-mini-llm.q8.json | Path to local mini-LLM weights used by llm
commands. |
| CORTEXA_LLM_HF_TOKEN | — | Optional Hugging Face token for authenticated dataset/model fetch workflows. |
| CORTEXA_DAEMON_RATE_LIMIT_MAX | 240 | Maximum request count per rate-limit window when limiter is enabled. |
| CORTEXA_METRICS_REQUIRE_AUTH | true | Protect /metrics
behind daemon authentication checks. |
| CORTEXA_MEM_COMPACT_BROTLI_QUALITY | — | Brotli compression quality level (0–11, higher favors ratio over speed) |