v1.2.0 — The audit-driven release

[idapixl]

Why this release exists

An external code-and-architecture review of cortex-engine landed on three credible critiques:

1. No public concurrency primitive. Multi-step writes — observation → memory promotion, dream consolidation, hindsight-driven definition revisions — chained await store.put* / update* calls without atomicity. A mid-sequence failure could leave orphan memories or a fade marker without its audit-trail belief entry.
2. No path between storage backends. The engine shipped SQLite and Firestore behind a clean CortexStore interface, but offered no tool to clone data from one to the other. The "abstract the persistence layer" recommendation from the audit was already done in code — but the plumbing that proves it (a migrator) was missing.
3. Tool discoverability hit a ceiling. Fifty-seven cognitive tools competing for an LLM's attention through one-line descriptions. The memory cluster (query vs recall vs retrieve vs neighbors vs wonder vs speculate) was genuinely ambiguous from names alone.

A fourth track landed during integration: a user-reported regression where fozikio health, vitals, anomalies, maintain fix, and a handful of other CLI subcommands silently ignored the agent's default_namespace and the --namespace flag, returning zero-stat results in any workspace that wasn't using the default namespace.

This release addresses all four, with parallel implementation tracks and a final code review pass.

What's new

withTransaction on every CortexStore

await store.withTransaction(async (txn) => {
  const memId = await txn.putMemory(memoryFields);
  await txn.putEdge({ source_id: memId, target_id: parentId, ... });
  await txn.markObservationProcessed(observationId);
});

If any line throws, the whole sequence rolls back. SQLite uses manual BEGIN IMMEDIATE / COMMIT / ROLLBACK with a per-store Promise-chained mutex (better-sqlite3's own db.transaction rejects Promise returns and doesn't survive await suspensions — we caught this empirically and rebuilt the implementation around the actual constraint). Firestore uses runTransaction with a FirestoreTxnProxy that routes writes through the transaction handle while explicitly throwing on scans (Firestore's reads-before-writes model).

busy_timeout = 5000 is now set on every SQLite store after journal_mode = WAL, so concurrent writers ride out checkpoint contention instead of failing instantly with SQLITE_BUSY.

Full contract: docs/concurrency.md.

fozikio migrate

# Backup
fozikio migrate --from sqlite:./cortex.db --to json:./backup.json --verify

# Restore into a fresh location
fozikio migrate --from json:./backup.json --to sqlite:./restored.db

# Upgrade path: local → cloud
fozikio migrate --from sqlite:./cortex.db --to firestore:my-project --verify

# Resume an interrupted migration
fozikio migrate --from sqlite:./cortex.db --to firestore:my-project --resume

Migrations are ID-preserving (so links survive), idempotent (re-running with --resume is safe), checkpointed (.cortex-migrate-state.json), and fail loudly on schema mismatch before mutating the destination. Three backends supported today — sqlite:, firestore:, json: — with adapters added by implementing CortexStore.

JSON is the third backend introduced here, primarily as a backup format and migration staging target. It loads the whole dataset into memory and rewrites the file on every write, so don't run a live agent off it.

Typed tool metadata

Every cognitive tool now carries:

interface ToolDefinition {
  name: string;
  description: string;        // 1-2 sentences naming the return shape
  category: ToolCategory;     // 13 categories: memory, consolidation, beliefs, ...
  whenToUse: string;          // one sentence; agent-facing
  doNotUse?: string;          // disambiguator vs adjacent tools
  inputSchema: { ... };
  handler: (...) => Promise<...>;
}

The MCP tools/list response composes these into the description the LLM sees:

[memory] Returns memories ranked by semantic similarity to a query string, with retrievability and salience weighting applied.

Use when: The agent has a natural-language question and wants matching memories ranked by relevance.
Don't use when: The agent already knows the exact memory ID — use `retrieve` instead.

All 57 tool descriptions were rewritten to a consistent quality bar, with extra attention to the memory cluster (the highest-confusion area). The full catalogue is auto-generated at docs/tools-reference.md, regenerable via npm run docs:tools.

Browse from the command line:

fozikio tools                          # everything by category
fozikio tools --category memory        # one category
fozikio tools --search "duplicate"     # name/description/whenToUse search
fozikio tools --json                   # machine-readable

A new REST endpoint exposes the same structured metadata:

GET /tools         → { tools: ToolMetadata[] }
GET /tools/:name   → ToolMetadata

CLI namespace fix

If you ran fozikio health in a workspace with default_namespace: anthems and got zero stats while the MCP server backed by the same SQLite file was correctly serving 18 memories — that bug is fixed. A new src/bin/namespace-resolver.ts helper threads --namespace, --agent, and the agent.yaml default through every subcommand. Affected commands: health, vitals, anomalies, maintain (both fix and re-embed), report, digest, wander. The resolved namespace is now printed to stderr on every run for visibility.

Migration path

For existing v1.1.x users: No breaking changes for tool authors who don't implement CortexStore. The interface grew six new methods (withTransaction, five upsert* variants, getCapabilities), so any external CortexStore implementations need to add them — see the existing implementations in src/stores/ for the pattern.

For plugin authors who add tools: ToolDefinition.category and whenToUse are now required fields. The TypeScript compiler will flag any plugin tool that doesn't have them. Valid categories: memory, consolidation, beliefs, ops, threads, journal, social, content, graph, vitals, agents, maintenance, meta.

For agents in production: Recommended pre-upgrade step:

fozikio migrate --from sqlite:./cortex.db --to json:./cortex-1.1.x-backup.json --verify

This gives you a frozen snapshot of your agent's mind before the upgrade. Restore is symmetric if needed.

Known limitations shipped intentionally

• Firestore migration is stubbed. The iteration adapters narrow on SqliteCortexStore / JsonCortexStore via instanceof; Firestore as a migration source or destination throws a clear error. The public CortexStore interface lacks listAll* methods for signals, beliefs, edges, ops, and observations, and we chose not to extend it mid-release. Workaround for now: route via JSON if you need Firestore↔X. Follow-up issue tracking this.
• JsonCortexStore is a tool, not a backend. It rewrites the file on every write and holds everything in memory. Use it for backup, restore, and migration. Do not host a live agent on it.
• Single-process MCP server is still the supported deployment for SQLite. Cross-process locking is not provided; multiple processes pointed at the same SQLite file is unsupported. Firestore is the answer for multi-process topologies.

Internal numbers, for the curious

• 110 tests across 14 files (up from 37 in 8 files).
• 6 new spec docs committed to the repo.
• 57 tool descriptions rewritten.
• 7 CLI commands gained namespace awareness.
• ~25 multi-step write paths surveyed; 8 wrapped in withTransaction.

Thanks

To the reviewer who delivered the audit that drove this work — your assertions were precise enough to plan around, your three "next steps" mapped cleanly onto three implementation tracks, and the one detail you got wrong (the dependency profile) was a useful Rorschach for catching out future LLM-driven reviews.

To the user who reported the namespace bug mid-release — you saved us from shipping a regression that would have been embarrassing to find later.

Full changelog

CHANGELOG.md has the comprehensive list.

Discussion

What's missing? What broke? What should v1.3.x focus on? Reply below.