v1.2.1 — CLI/MCP table-name asymmetry fix

Fixed

CLI/MCP table-name asymmetry on collections_prefix values ending in _.

v1.2.0's src/bin/namespace-resolver.ts stripped a trailing underscore from collections_prefix before passing it to SqliteCortexStore, while src/mcp/server.ts had always passed the value verbatim. Both feed into the same ${this.ns}_${name} table-name builder at src/stores/sqlite.ts:301, so for any prefix ending in _ the two paths read and wrote different tables.

Concretely: a workspace with agent.yaml set to collections_prefix: anthems_ would see the MCP server write to anthems__memories while fozikio health --agent anthems queried the empty anthems_memories. The output was indistinguishable from the pre-v1.2.0 broken behaviour the resolver was introduced to fix.

The resolver now returns collections_prefix verbatim, matching the MCP server's de facto behaviour. MCP wrote first in real deployments, so its table layout is ground truth; aligning CLI to MCP preserves existing data with zero migration. The reverse fix (stripping in MCP too) would have orphaned every existing namespace's memories.

Test

namespace-resolver.test.ts renamed and inverted:

• was: prefers collections_prefix (trailing underscore stripped) when set
• now: uses collections_prefix verbatim (no trailing-underscore strip)

110/110 tests still passing.

Upgrade

npm install @fozikio/cortex-engine@1.2.1

No config changes required. If you're on v1.2.0 and your CLI commands have been reporting suspiciously empty stats while MCP queries work fine, this is your fix — upgrade and your data becomes visible to both paths simultaneously.

Full Changelog: v1.2.0...v1.2.1

v1.2.0 — audit-driven release: withTransaction, JsonStore, migrate CLI, tool catalogue

The audit-driven release

An external code-and-architecture review of cortex-engine surfaced three credible critiques: missing concurrency primitives, no path between storage backends, and 27+ MCP tools competing for an LLM's attention with no disambiguation guidance. This release addresses all three as parallel implementation tracks, plus a fourth track that landed mid-flight when a user reported that CLI subcommands were silently dropping the agent namespace.

Added

• CortexStore.withTransaction(fn) — backend-native atomic-write primitive for composing multi-step writes. SQLite uses manual BEGIN IMMEDIATE / COMMIT / ROLLBACK with a per-store Promise-chained mutex (better-sqlite3's own db.transaction rejects Promise returns and does not survive await suspensions). Firestore wraps runTransaction with a FirestoreTxnProxy routing writes through the transaction handle. Full contract in docs/concurrency.md.
• CortexStore.upsertMemory(...) and siblings for Observation, Edge, OpsEntry, Signal, BeliefEntry — ID-preserving variants of put* for migration and restore. Implemented in SQLite, Firestore, JSON, and ScopedStore.
• CortexStore.getCapabilities() — { schemaVersion, embeddingDimension, categories, namespace, backend } snapshot used by migrate to refuse incompatible source/destination pairs before mutating data.
• JsonCortexStore — a third storage backend backed by a single JSON file with atomic temp+rename persistence. Intended for backup, restore, and migration staging — not a production server-side store.
• fozikio migrate --from <url> --to <url> — new CLI command that clones data between any pair of supported backends. Supports --namespace, --rename-namespace, --resume, --verify, --dry-run, --allow-merge, --batch-size. Idempotent (upsert-by-ID), checkpointed (.cortex-migrate-state.json), fails loudly on schema mismatch.
• fozikio tools — new CLI for browsing the cognitive tool catalogue by category.
• GET /tools and GET /tools/:name REST endpoints returning structured ToolMetadata.
• ToolDefinition.category + whenToUse + doNotUse — typed metadata on every tool. The MCP ListTools response composes these into the description string so the LLM has explicit disambiguation guidance.
• docs/concurrency.md, docs/tools-reference.md (auto-generated, 57 tools by category, regenerable via npm run docs:tools), docs/storage-backends.md.

Changed

• SQLite busy_timeout = 5000 is now set immediately after journal_mode = WAL. Concurrent writers ride out checkpoint contention for up to 5 seconds before surfacing SQLITE_BUSY.
• Multi-step write paths use withTransaction in cognition.ts, believe.ts, forget.ts, and observe.ts. A mid-sequence failure during dream consolidation no longer leaves orphan memories, edges, or unprocessed observations.
• All 57 tool descriptions rewritten to a consistent quality bar with whenToUse / doNotUse for disambiguation.
• wonder and speculate salience schema corrected from 1-10 (default: 5) to 0.0-1.0 (default: 0.5).

Fixed

• CLI subcommands no longer drop the agent namespace. fozikio health, vitals, anomalies, maintain fix, report, digest, and wander now resolve via src/bin/namespace-resolver.ts, honouring --namespace, --agent, then config default.
• Orphan-memory window during high-salience observation promotion — observe.ts wraps putMemory + markObservationProcessed in a transaction.
• Audit-trail gap during forget — forget.ts wraps updateMemory + putBelief.
• Confidence/definition split in hindsight review — cognition.ts:hindsightReview lands both in a single transaction.

Internal

• 73 new tests across six files; total suite is now 110 tests.

Note: A regression in this release's CLI namespace resolution was fixed in v1.2.1. If you set collections_prefix ending in _, upgrade to v1.2.1.

Full Changelog: v1.1.1...v1.2.0

v1.1.1 — HyDE query crash fix

Fixed

HyDE query crash on empty LLM output — query(hyde: true) could crash with Cannot read properties of undefined (reading 'length') when a reasoning-mode LLM (qwen3, phi4-reasoning, etc.) consumed the entire maxTokens budget on the <think>...</think> block, leaving an empty final response. stripThinking() then yielded "", and OllamaEmbedProvider.embed("") returned undefined (Ollama returns embeddings: [] for empty input, and [][0] is undefined). The undefined embedding propagated as the query vector and crashed on .length access in spread activation.

Three layers of fix

• hydeExpand (src/engines/memory.ts) — prepends /no_think to suppress reasoning-mode output (mirroring the pattern generateJSON already used), and falls back to embedding the raw query if the LLM still produces empty output.
• OllamaEmbedProvider.embed (src/providers/ollama.ts) — throws on empty input and validates the response has a non-empty embedding (fail-fast instead of returning undefined).
• spreadActivation (src/engines/memory.ts) — defensive null guard on memory.embedding.length, matching the optional-chaining pattern already used elsewhere in the function (Memory.embedding is typed number[] | null).

Added

• HyDE fallback regression test (src/engines/hyde-fallback.test.ts) — 3 tests covering empty LLM output, whitespace-only output, and substantive output paths.
• Spread-activation null-embedding regression test (src/engines/spread-activation.test.ts) — covers the previously-unguarded memory.embedding.length access.
• scripts/verify-hyde-fix.mjs — standalone Node script that exercises the HyDE → findNearest → spreadActivation chain against a live SQLite store, useful for debugging future query path crashes.

Also in this release

• feat(config-loader): support llm/embed/store options and cognitive_tools in NamedCortexEntry, enabling multi-agent setups where one named agent owns one cortex namespace with its own tool subset directly from agent.yaml.

Full diff: v1.1.0...v1.1.1

v1.1.0 — Kimi (Moonshot) provider, long-context dream, variable ops TTL, security hardening

Added

• Kimi (Moonshot AI) provider — llm: kimi is now a first-class config option. Set MOONSHOT_API_KEY and the engine auto-configures against api.moonshot.cn/v1. Optionally override the model via llm_options.kimi_model (default: kimi-k2-0711-preview).
• Long-context dream strategy — DreamOptions.strategy: 'long-context' replaces the Phase 4 (Connect) N² pairwise edge discovery with a single LLM call that sees the full memory graph (up to 200 nodes + all existing edges). The model finds transitive patterns, cross-domain contradictions, and causal chains that the sequential approach structurally cannot detect. Works with any large-context model; long_context_memory_limit controls the cap (default: 200).
• Variable TTL for ops entries — ops_append now uses type-based expiry: log 90 days, instruction/handoff 14 days, milestone 180 days, decision 365 days. Previously all entries expired after 30 days.
• Expanded ops schema — ops_append accepts session_type, seed_type, blocked, next, instruction_meta, and handoff_meta fields. ops_query returns these fields. ops_update supports next and blocked.
• Thread creation warnings — thread_create now returns warnings when next_step or project is missing, guiding agents toward higher-quality thread creation.

Security

• Timing-safe authentication — REST server auth comparison uses crypto.timingSafeEqual to prevent timing attacks.
• Plugin path sandboxing — Plugin loader validates import paths against trusted directories, blocking loads from untrusted locations.
• REST tool blocklist — Destructive tools (forget, dream, evolve, resolve, thread_resolve) are blocked from the generic REST /api/tools/:name endpoint. They remain available via MCP (direct agent access).
• SQLite namespace validation — Namespace names must be alphanumeric/underscore only, preventing SQL injection via namespace parameter.
• Parameterized SQLite queries — LIMIT clause in ops queries is now parameterized instead of interpolated.
• API key config warning — config-loader warns when openai_api_key is found in config files instead of environment variables.

Full Changelog: v1.0.0...v1.1.0

v1.0.0 — Plugin Absorption: all 57 cognitive tools consolidated into core engine

Major Release — Plugin Absorption

All cognitive tools are now built directly into cortex-engine. No separate plugin installs needed.

Previously, extending the engine required separate npm packages:

npm install @fozikio/tools-threads
npm install @fozikio/tools-journal
# etc.

Now, all 57 tools come with the core install:

npm install @fozikio/cortex-engine

Absorbed packages

The following packages are now included in cortex-engine core and are no longer required as separate installs for v1.0.0+:

Package	Tools Added
@fozikio/tools-threads	thread_create, thread_update, thread_resolve, threads_list
@fozikio/tools-journal	journal_write, journal_read
@fozikio/tools-content	content_create, content_list, content_update
@fozikio/tools-evolution	evolve, evolution_list
@fozikio/tools-social	social_read, social_update, social_draft, social_score
@fozikio/tools-graph	graph_report, link, suggest_links, suggest_tags
@fozikio/tools-maintenance	retrieve, forget, find_duplicates, sleep_pressure, consolidation_status, retrieval_audit
@fozikio/tools-vitals	vitals_get, vitals_set, sleep_pressure
@fozikio/tools-reasoning	surface, ruminate, notice, intention, resolve, query_explain, contradict

New in v1.0.0

• 57 cognitive tools (up from 27 in v0.x)
• All tools live in individual files under src/tools/ — easier to read, extend, and contribute to
• Richer implementations: observe now auto-scores via LLM, predict uses temporal reranking
• New store methods: countDocuments() and delete() on both SQLite and Firestore backends
• Shared _helpers.ts for argument parsing and event firing across all tools

Migration from v0.x

If you were using separate @fozikio/tools-* packages, simply:

1. Update cortex-engine: npm install @fozikio/cortex-engine@latest
2. Remove the separate plugin installs — tools are now built-in
3. Remove plugin references from your agent.yaml config (if any)

The plugin system still works for custom extensions you've built yourself.

Tools toggling

All tools can be enabled/disabled via the cognitive_tools config key in agent.yaml. By default, all 57 tools are enabled.

Full Changelog: v0.10.0...v1.0.0

v0.9.3 — Deprecation Stub (use @fozikio/cortex-engine)

Deprecation Notice

This version was published to the old cortex-engine npm package as a deprecation stub.

If you installed cortex-engine (unscoped), v0.9.3 redirects you to the new scoped package:

npm uninstall cortex-engine
npm install @fozikio/cortex-engine

The real, actively maintained package is @fozikio/cortex-engine.

This release also includes security hardening and CI improvements:

• Resolved all 7 GitHub code scanning security alerts (path traversal, ReDoS, info leakage)
• Docker onboarding (Dockerfile, docker-compose, GHCR publish workflow)
• REST server with bundled dashboard
• Dependabot dependency updates

Full Changelog: v0.9.2...v0.9.3

v0.9.2 — Rename to @fozikio/cortex-engine

What's Changed

Package renamed from cortex-engine to @fozikio/cortex-engine.

• Scoped under the @fozikio npm organization
• @huggingface/transformers moved to optional peerDependency (fixes BundlePhobia size reporting)
• Added try/catch with helpful error message when transformers is missing
• Updated all docs, skills, and install commands to use the scoped package name

Migration

npm uninstall cortex-engine
npm install @fozikio/cortex-engine

Import paths remain the same — just the package name changed.

Full Changelog: v0.9.1...v0.9.2

v0.9.1 — Dream Pipeline Fixes

What's Changed

Bug fixes for the dream/digest pipeline:

• Dream create phase: fall back to content_type heuristic when LLM classification returns empty (common with Gemini safety filters)
• Mark failed/broken observations as processed to prevent infinite dream cycling
• Add diagnostic logging for content_type breakdown and errors
• Include digest extraction pipeline (extract step for typed content ingestion)

Full Changelog: v0.9.0...v0.9.1

v0.9.0 — Neuroscience-Grounded Cognitive Architecture

What's New

16 cognitive improvements derived from three expert analyses (computational neuroscience, CS theory, information geometry / simulation theory).

Retrieval

• Query-conditioned BFS — spreading activation now weights edges by query relevance (Synapse paper, arXiv:2601.02744)
• GNN neighborhood aggregation — retrieval scores incorporate graph neighbor context, not just isolated node similarity
• Multi-anchor retrieval — Thousand Brains-inspired consensus voting across multiple query formulations
• Adaptive clustering — thresholds auto-adjust based on local embedding density (information geometry)

Consolidation

• Two-phase dream — dreamPhaseA() (NREM: compress) + dreamPhaseB() (REM: integrate) — modeled on biological sleep stages
• Cluster evidence preservation — observation content is now retained during clustering, fixing the highest information-loss point in the pipeline
• Temporal replay ordering — observations processed in creation order, matching biological consolidation sequence
• Abstraction provenance — exemplifies edges link abstractions back to source memories
• Schema congruence scoring — sparse-neighborhood observations held as episodic rather than prematurely clustered
• Post-refinement edge re-validation — edges are checked for continued validity after memory definitions change
• FSRS interval filter — only reviews memories actually due, reducing Phase 5 from O(n) to O(scheduled)

New Cognitive Features

• goal_set tool — store desired future states that generate forward prediction error (VTA/dopamine value channel)
• Epistemic foraging — wander is now information-gain-weighted, biasing toward under-explored, uncertain, and goal-adjacent memories
• Fiedler value metric — algebraic connectivity of the memory graph, measuring knowledge integration quality
• PE saturation detection — monitors prediction error trends to prevent identity schema ossification

Infrastructure

• getRecentMemories(days, limit) — time-bounded store queries for O(1) scaling (SQLite + Firestore + ScopedStore)
• First test file — 8 unit tests for retrieval functions

Stats

• 1,275 lines added across 15 files
• 3 new files: graph-metrics.ts, goal.ts, memory.test.ts
• 27 MCP tools (was 26)
• Zero breaking changes — all existing APIs preserved

Full npm: npm install cortex-engine@0.9.0

v0.8.0 — OpenAI-Compatible Provider + Agent Invoke

What's New

OpenAI-Compatible LLM Provider

One adapter that unlocks the entire LLM ecosystem beyond Ollama and Vertex AI:

• OpenAI (GPT-4o, GPT-4o-mini)
• DeepSeek (V3.2 — $0.28/M input, great for agents)
• Hugging Face Inference (free tier available)
• OpenRouter (access any model)
• Together AI, Fireworks AI
• LM Studio, vLLM (local servers)

Auto-detects provider from environment variables — just set your API key and go:

# fozikio.json
llm: openai
llm_options:
  openai_model: deepseek-chat
# Set DEEPSEEK_API_KEY env var — base URL auto-detected

agent_invoke Tool

New MCP tool that dispatches tasks to a cortex-backed agent using your configured LLM:

1. Queries cortex for existing knowledge about the topic
2. Builds context-aware prompt with what's already known
3. Runs the LLM (Ollama, Gemini Flash, DeepSeek — whatever you configured)
4. Stores findings back into cortex as observations
5. Returns results with full provenance

This replaces expensive host-agent subagents with cheap, knowledge-accumulating cortex agents. Findings compound across sessions — the second time you research a topic, the agent already knows what it found last time.

cortex.agent_invoke({
  task: "Research FSRS scheduling algorithms",
  store_results: true
})

Why This Matters

The LLM provider + agent_invoke combination means cortex can now think on its own using cheap models, while the host agent (Claude, Gemini, etc.) focuses on complex reasoning. Background tasks, research, analysis — all at pennies per call instead of subscription tokens.

Breaking Changes

None. Existing ollama and gemini configurations continue to work unchanged.

Full Changelog

• feat: v0.8.0 — OpenAI-compatible LLM provider
• feat: agent_invoke tool — cortex-backed agent dispatch
• fix: dream abstraction truncation — increase token limit, validate completeness
• fix: reframe init output to emphasize modular namespace architecture