Skip to content

Roadmap

Stage 0: Documentation Init

Goal: define the project before implementation.

Deliverables:

  • README.
  • Product vision.
  • Requirements.
  • Architecture overview.
  • Package boundaries.
  • Storage model.
  • Memory model.
  • MCP and CLI tool contract.
  • Init specification.
  • Privacy and security model.
  • Testing strategy.
  • Release, publishing, and versioning policy.

Exit criteria:

  • A contributor can understand what to build without guessing package responsibilities.
  • Runtime memory location is clear.
  • Public contracts are documented.

Stage 1: Core MVP

Goal: implement local memory lifecycle.

Status: implemented for the MVP, including audit history, transactional SQLite mutations, safe bulk forgetting, import preflight, migration coverage, and expanded secret detection.

Deliverables:

  • packages/core.
  • TypeScript workspace scaffold.
  • SQLite migrations.
  • FTS search.
  • audit events.
  • secret scanner.
  • import/export.
  • core tests.

Exit criteria:

  • Core can run without CLI or MCP.
  • All memory lifecycle operations are tested.

Stage 2: CLI

Goal: give users direct control.

Status: implemented in packages/cli, with user/project initialization, the full memory lifecycle, stable exit codes, and installed-package smoke coverage.

The monorepo exposes the local CLI through npm run nuzo --.

Deliverables:

  • nuzo memory init.
  • remember, recall, list, update, forget.
  • export/import.
  • doctor.
  • local smoke test command.

Exit criteria:

  • User can manage memory without an agent.
  • CLI exits with stable error codes.

Stage 3: MCP Server

Goal: make memory available to agents.

Status: implemented in packages/mcp-server with 19 tools, protocol-level SDK tests, read-only lifecycle recall, read-only capture suggestion validation, and runtime doctor diagnostics.

Deliverables:

  • MCP tool schemas.
  • MCP handlers calling core use cases.
  • contract tests.
  • setup docs.
  • read-only doctor diagnostics for host agents.
  • read-only capture suggestion validation before confirmed writes.

Exit criteria:

  • Codex or another MCP-compatible agent can manage memory through the server.

Stage 4: Host Plugins

Goal: package the MCP server for agent hosts through supported plugin workflows.

Status: repository marketplaces, release layouts, host guidance, native installation validation, and artifact validation are implemented. Tracked and generated Codex and Claude Code layouts resolve the matching published @nuzo/memory runtime.

The release layout is generated under build/plugins/. It keeps host wrappers thin and resolves a version-pinned @nuzo/memory package instead of a monorepo sibling path.

Deliverables:

  • .codex-plugin/plugin.json.
  • .claude-plugin/plugin.json.
  • plugin READMEs.
  • Codex-specific setup docs aligned with the official plugin path.
  • Claude Code setup docs aligned with the official plugin path.
  • lifecycle hook policy for recall/capture in hosts that support hooks.
  • capture suggestion contract for inferred memories with no silent writes.
  • MCP-level read-only recall hook prototype.
  • MCP-level read-only capture suggestion validation.
  • Marketplace or official distribution metadata when the supported workflow is stable.
  • matching MCP package publication before public plugin installation.
  • reproducible npm pack validation and clean tarball installation.

Exit criteria:

  • Codex plugin can be packaged through a supported Codex plugin workflow and used in a fresh Codex session.
  • Claude Code plugin can be packaged through a supported Claude Code plugin workflow and used in a fresh Claude Code session.
  • Recall/capture hooks follow the lifecycle and capture suggestion specs before host automation.
  • No development-only installer is required for normal use.

Stage 5: Public Release

Goal: publish the project.

Status: repository, license, contribution/security files, CI, Pages, custom domain HTTPS, npm packages, clean host-plugin validation, and versioned release tags are complete.

Deliverables:

  • GitHub repository.
  • Apache-2.0 license.
  • SECURITY.md.
  • CONTRIBUTING.md.
  • docs site on nuzo.com.br.

Exit criteria:

  • No private memory files tracked.
  • Install docs work from a clean environment.

Stage 6: Post-MVP Distribution

Goal: make routine releases and host installation easier without weakening the local-first product boundary.

Status: complete for current release infrastructure. Scope authorization, optimistic concurrency, effective runtime configuration, Dependabot, CodeQL, branch protection, npm trusted publishing, provenance, and public artifact validation are implemented.

Completed:

  • optional restricted scope authorization for shared host or project stores;
  • optimistic concurrency control for independent local processes;
  • effective user and project runtime configuration;
  • Dependabot, CodeQL, secret scanning, push protection, and required checks on main;
  • pull-request-only routine changes with administrator branch protection and strict required checks;
  • a manual GitHub Actions OIDC workflow for npm dry runs and publishing;
  • trusted npm publication with SLSA provenance for @nuzo/memory-core, @nuzo/memory, and the legacy transition packages.

Moved to the 0.8.0 Host Reliability goal:

  • publish Codex and Claude Code marketplace listings;
  • validate complete real Codex and Claude Code workflows across sessions;
  • gather installation feedback without telemetry.

Stage 7: Real Workflow Hardening

Goal: prove that Nuzo feels useful in real agent work, not only in source-tree tests.

Status: complete in 0.1.2. The published CLI and MCP packages, generated Codex plugin artifact, generated Claude Code plugin artifact, and capture suggestion rules now have automated continuity and safety validation.

Detailed validation plan: docs/operations/post-release-validation.md.

Deliverables:

  • installed CLI session-continuity smoke;
  • installed MCP stdio session-continuity smoke;
  • Codex plugin release-artifact recall and capture suggestion validation;
  • Claude Code plugin release-artifact recall and capture suggestion validation;
  • documented capture suggestion criteria for confirmed writes;
  • focused GitHub Issues for any host limitation or manual validation gap.

Exit criteria:

  • a fake durable memory stored in one session is recalled in a fresh session;
  • memory.recall_hook stays read-only;
  • memory.suggest_capture never persists inferred drafts before confirmation;
  • host plugins remain thin wrappers around the published MCP runtime;
  • docs describe only install and verification paths that were tested.

Stage 8: Product Polish And Install Simplification

Goal: make Nuzo easier to understand, install, and use before adding another large capability layer.

Status: shipped in 0.1.3.

The package recommendation in this historical stage was later superseded by the unified @nuzo/memory package.

This stage should reduce public complexity, not add more surface area. The technical package boundaries can stay clean while the public onboarding presents one obvious path for normal users.

Deliverables:

  • trim README.md into a fast product entry point with a 60-second install and first-use path;
  • explain the package split as user-facing roles: CLI for humans, MCP server for agent hosts, core for library/integrator use;
  • historical: make @nuzo/memory-cli the default package users see first during the early split-package phase. Current releases use unified @nuzo/memory as the recommended package;
  • add or improve clean install docs for CLI, MCP host, Codex, and Claude Code without requiring a source checkout;
  • reduce AGENTS.md to safe public guidance and move local/operator-only preferences to ignored AGENTS.local.md;
  • keep CONTRIBUTING.md as the public contribution entry point for humans and external bots;
  • audit root and docs Markdown naming conventions, keeping conventional uppercase root files and lowercase kebab-case docs paths;
  • classify docs as user docs, maintainer docs, architecture/spec docs, or temporary/internal notes;
  • remove, merge, or move docs that do not help users, contributors, maintainers, or durable architecture decisions;
  • update site navigation so the first path is installation/use, not the project construction history;
  • keep release, security, versioning, and public contract docs discoverable but out of the first-time user path.

Exit criteria:

  • a new user can identify the right install path without understanding all npm packages;
  • the README links out to details instead of duplicating them;
  • no tracked public file contains local operator notes, tokens, private workflow preferences, or instructions that should only apply to this machine;
  • Markdown file naming has a documented pattern and obvious exceptions;
  • remaining docs have a clear audience and owner.

Non-goals for this stage:

  • merging the published npm packages only to reduce their count;
  • adding cloud sync, embeddings, or automatic write hooks;
  • replacing CONTRIBUTING.md with agent-specific instructions;
  • adding local installer scripts before official setup and update paths are clear.

Stage 9: Agent Memory Lifecycle

Goal: make Nuzo feel integrated and intelligent in CLI agent workflows while keeping memory local, inspectable, and user-controlled.

Status: shipped in 0.2.0 as the first agent memory lifecycle milestone.

This stage is the bridge from "Nuzo exposes memory tools" to "Nuzo gives agent sessions a real memory loop." The user experience should feel familiar to modern assistant memory: an agent recalls useful context at the start of a new session, notices durable preferences or project decisions during work, proposes what should persist, and carries confirmed memories into later sessions.

The implementation boundary stays conservative:

new agent session
  -> memory.recall_hook
  -> read-only context
conversation
  -> candidate detection by host or agent guidance
  -> memory.suggest_capture
  -> editable user confirmation
  -> memory.confirm_capture
later session
  -> recalled confirmed memory

There is no silent inferred write path by default.

Deliverables:

  • Codex-first task-start read-only recall flow that calls memory.recall_hook before work that depends on prior context;
  • host guidance for explicit user commands such as "save this in Nuzo memory" or "remember this for this project";
  • lightweight intelligent capture rules for durable preferences, project decisions, recurring instructions, stable facts, and workflow notes;
  • editable capture confirmation flow where the user can confirm, edit, or reject each suggested memory;
  • exact duplicate handling before prompts, with existing memories shown instead of creating redundant records;
  • update/conflict handling for changed memories, preferring confirmed updates with expected revisions over duplicate writes;
  • confirmed writes and confirmed edits through memory.confirm_capture;
  • forget/archive guidance in host workflows;
  • audit trail documentation for created, updated, archived, deleted, imported, exported, and optional recall events;
  • user-facing docs showing the real loop: one session confirms a memory, a later Codex or Claude Code session recalls it;
  • dogfooding examples for Nuzo development that are safe to publish and do not include private operator notes;
  • a small local benchmark for recall, duplicates, conflicts, forget, export, import, and latency on small and medium stores.

Host order:

  1. Codex plugin and skill behavior.
  2. Claude Code plugin and skill behavior through the same MCP contract.
  3. Generic MCP-host guidance for future CLI agents.

Exit criteria:

  • a fresh Codex session can recall a confirmed memory saved in an earlier session without manual CLI commands;
  • a direct user instruction to remember something creates an inspectable draft before writing;
  • a likely durable preference or project decision can be suggested without writing until the user confirms;
  • rejected drafts leave no stored memory, audit event, or hidden note;
  • confirmed drafts remain normalized, policy-checked, auditable, and portable;
  • duplicate candidates do not create duplicate active memories by default;
  • changed memories use update/conflict behavior instead of unbounded new rows;
  • the same Nuzo store can serve Codex, Claude Code, and direct CLI audit flows;
  • benchmark results are reproducible locally without telemetry or network calls.

Non-goals for this stage:

  • hidden automatic memory writes;
  • cloud sync;
  • remote embeddings or remote LLM calls by default;
  • graph memory as the default storage model;
  • dashboard UI;
  • multi-user or team sync;
  • importing private native memory from a host without an official export path;
  • automatic LLM compression without explicit user confirmation.

Planned Release Sequence

The completed stages above preserve the history and rationale that produced Nuzo 0.3.0. Current planning is organized by release goals with explicit deliverables and exit criteria:

  1. 0.3.1: trust baseline (shipped);
  2. 0.4.0: audit and provenance (shipped);
  3. 0.5.0: recall quality (shipped);
  4. 0.6.0: capture intelligence (shipped);
  5. 0.7.0: optional semantics (shipped);
  6. 0.8.0: host reliability (shipped);
  7. 0.9.0: contract stabilization (shipped);
  8. 1.0.0: stable release (shipped);
  9. 1.1.0: MCP Registry distribution and adoption polish (shipped);
  10. 1.2.0: final hardening and end of maintenance (final release).

See Release Goals for the scope, non-goals, and exit criteria of each release. The stable user-experience target is defined in the 1.0.0 Developer Experience Contract. GitHub milestones mirrored those release boundaries. The 1.2.0 release closes the planned roadmap; no future feature milestone is maintained.

Post-1.0 Adoption Focus

Goal: make the stable Nuzo 1.0 contract easy for new developers to understand, trust, install, and evaluate before adding another major capability layer.

Status: complete. The repository adoption surface is implemented, including the decision guide, public-package demo, comparison, and launch playbook. No external launch-post campaign or continuing feedback program is planned.

Nuzo 1.0.0 moved the main risk from contract stability to adoption. The next work should explain the product clearly, answer likely objections, and create a short reproducible path from installation to cross-session recall.

Tracked by GitHub Issue #289.

Deliverables:

  • a concise public launch narrative for Nuzo 1.0;
  • a direct answer to "why not just AGENTS.md, MEMORY.md, or native assistant memory?";
  • honest positioning against adjacent tools such as Mem0, Zep, server-memory, and native assistant memory;
  • a short demo path that installs Nuzo, saves a memory, starts a fresh session, and recalls it;
  • README and home-page copy tuned for a first-time visitor deciding quickly whether Nuzo is worth installing;
  • a deliberate public feedback path through GitHub Issues or Discussions;
  • a launch checklist for registries, lists, and announcement posts.

Non-goals:

  • cloud sync, telemetry, remote embeddings, or silent write automation;
  • a new npm release as part of the adoption-planning work;
  • unsupported adoption metrics or invented npm download numbers;
  • feature work that does not directly reduce adoption friction.

Exit criteria:

  • a first-time developer can understand Nuzo's value, safety boundary, and install path without reading maintainer-only docs;
  • public docs answer the strongest objections before asking the user to install another tool;
  • feedback channels are intentionally configured and discoverable;
  • the final release and end-of-maintenance posture are explicit and do not imply continuing feature or support work.

End Of Maintenance

Nuzo 1.2.0 is the final planned release. The repository is archived after the release artifacts, registry entry, and security advisories are verified. Deferred sync, encryption, UI, governance automation, performance tuning, and distribution work will not be implemented upstream. See End Of Maintenance for the support and fork policy.