feat: manage deja-vu as an optional cross-host session-memory companion

[pacphi]

Executive brief

Add first-class, opt-in management of deja-vu as a cross-host session-history companion.

deja-vu indexes the local histories that Claude Code, Codex, OpenCode, Cursor, and other coding harnesses already wrote to disk, then exposes recall through MCP and optional session-start hooks. This complements the existing Ruflo/AgentDB memory plane:

• Ruflo/AgentDB remains authoritative for curated operational memory: project decisions, structured state, outcomes, reusable patterns, and agent continuity.
• deja-vu provides the searchable evidence archive: retroactive raw transcripts, commands, tool output, files touched, and edit spans across hosts.

Agentic Kit should manage the complete lifecycle for users who opt in:

intent → install → configure host wiring → build/refresh index → verify
       → detect drift → sync/repair → remove owned wiring/package safely

The integration must follow the same ownership, dry-run, idempotence, verification, and fail-closed rules as other managed tools. It must not model deja-vu as an execution host, inference provider, or AgentDB replacement.

Why this belongs in Agentic Kit

The current machine can easily accumulate gigabytes of Claude, Codex, and OpenCode history while only a curated subset reaches project memory. That creates a durable gap:

• work completed before Ruflo memory was enabled is not automatically backfilled;
• exact commands, error strings, tool output, and edit spans are often intentionally omitted from summaries;
• a solution found in Codex may not be visible when a later Claude session starts;
• project memory should remain concise and curated rather than becoming a verbatim transcript archive.

deja-vu is purpose-built for the archive side of that boundary. Its upstream CLI already provides:

• a published npm wrapper, @vshulcz/deja-vu, with platform binary packages;
• target-specific MCP wiring such as deja install claude-code, codex, and opencode;
• target-specific auto-recall wiring such as claude-auto, codex-auto, and opencode-auto;
• deja doctor --json with explicit store, index, MCP, and version states;
• deja uninstall <target> and deja uninstall --all;
• a local index and wiring record under XDG-aware paths;
• a documented no-clobber uninstall path that removes its entries while preserving unrelated host configuration.

Upstream references:

• README and install modes
• Security model
• Architecture
• Benchmarks

Current Agentic Kit architecture

The required seams already exist, but managed-tool behavior remains spread across tool-specific branches:

• src/commands/setup.mjs installs Ruflo, Agentic-QE, AgentDB, RuvNet Brain, and enabled hosts.
• src/commands/status.mjs emits health/drift rows and named remediations.
• src/commands/sync.mjs derives a plan from status, applies repairs, and recollects facts to prove convergence.
• src/commands/uninstall.mjs distinguishes footprint removal, package removal, purge, and project-data preservation.
• src/lib/versions.mjs owns npm installed/latest comparisons.
• src/lib/adapters/lifecycle.mjs defines the shared detect → plan → apply → verify → undo contract.
• tests/kit/adapter-lifecycle-conformance.test.mjs already enforces read-only detection, deterministic planning, non-mutating dry-run, idempotent apply, observed verification, and ownership-safe undo.
• docs/MANAGED-TOOLS.md defines the disk-first, single-updater, same-version-namespace, one-drift-story, and explicit-outcome invariants.

The governing ADRs are living plans:

• ADR-0016 is Accepted (2026-07-28; updated 2026-08-04). It requires capability-driven integrations, the shared lifecycle contract, value-precise ownership receipts, and setup/status/sync/verify/uninstall consuming the same normalized facts.
• ADR-0023 is Implemented (2026-08-04). It requires fail-closed mutations, explicit ok/degraded/failed/skipped outcomes, pre-mutation trust disclosure, and clean-machine proof.

There is one concrete documentation drift to fix as part of this work: docs/MANAGED-TOOLS.md still calls ADR-0016 “Proposed,” while the ADR itself is now Accepted.

Goals

1. Let users opt into deja-vu during setup or through an explicit command/config change.
2. Install a released deja-vu artifact using a package-manager path Agentic Kit can own and update.
3. Wire only the enabled/present Agentic Kit hosts selected by policy.
4. Default to MCP recall; make automatic context injection a separate explicit choice.
5. Build the initial index once, show progress, and verify it without exposing transcript content.
6. Surface presence, install method, ownership, version drift, wiring health, index health, and degraded states in ak status.
7. Make ak sync converge the package, wiring, and index without duplicate entries or repeated writes.
8. Remove only Agentic Kit-owned wiring and packages; preserve external installs and user-modified host configuration.
9. Preserve deja-vu's index, notes, exclusions, tombstones, policies, and imported history unless the user explicitly requests data purge.
10. Keep the integration local-first, zero-runtime-dependency, cross-platform, testable, and aligned with Agentic Kit's trust boundary.

Non-goals

• Replacing Ruflo memory or AgentDB.
• Copying every raw transcript into AgentDB.
• Treating deja-vu as an execution host, inference provider, routing target, or provider binding.
• Enabling auto-recall by default.
• Installing into every harness deja-vu detects regardless of Agentic Kit host intent.
• Adopting, updating, or deleting a Homebrew, Go, manually downloaded, or host-plugin installation.
• Calling deja update for an npm-managed install; upstream explicitly delegates npm installs to the package manager.
• Automatically enabling semantic embeddings or configuring an embedding endpoint.
• Automatically syncing history to another machine.
• Deleting source transcripts.
• Sending transcript content, paths, queries, or index records to status, telemetry, logs, or the Dashboard.

Primary use cases

1. Backfill existing history

A user enables deja-vu after months of Claude and Codex work. ak setup installs the binary, wires enabled hosts, runs one indexed warmup, and verifies the resulting index. No manual per-host configuration is required.

2. Cross-host recall

A bug solved in Codex is later queried from Claude. Both hosts use the same local deja-vu index through their native MCP configuration, while accepted conclusions can still be promoted into Ruflo/AgentDB project memory.

3. Exact incident forensics

A user needs the prior command, error string, file span, or rejected attempt that a curated summary omitted. deja-vu supplies the evidence archive without bloating structured memory.

4. Safe MCP-first adoption

A user wants on-demand recall but does not want historical context injected into every new session. The default managed mode wires MCP only and leaves session-start hooks absent.

5. Explicit auto-recall

A user opts into automatic recall for selected enabled hosts. Agentic Kit discloses the hook/plugin changes, transitions each host from its MCP target to the corresponding -auto target, and verifies that the old target is not left behind.

6. Drift repair

The npm package is upgraded, a host config loses its MCP entry, the binary path changes, or the index becomes stale. ak status reports the observed problem and ak sync performs the smallest owned repair.

7. External installation

deja-vu is already installed through Homebrew, Go, a downloaded binary, or a host plugin. Agentic Kit detects and can use/report it but does not update, uninstall, or adopt it without an explicit ownership transition.

8. Clean removal

A user runs ak uninstall. Agentic Kit removes only wiring it owns. An explicit package-removal flag removes an Agentic Kit-owned npm package after confirmation. Historical index data remains unless a separate destructive data-purge flag is confirmed.

Product principles

1. Complement, do not conflate. Structured project memory and transcript evidence remain separate roles.
2. Opt-in because history is sensitive. No transcript scan, index build, MCP registration, or hook installation happens from defaults alone.
3. MCP before injection. Default managed mode is on-demand MCP recall.
4. Host intent controls wiring. Enabled Agentic Kit hosts determine eligible deja-vu targets.
5. Presence is not ownership. External binaries, plugins, and pre-existing config remain externally owned.
6. One package update owner. Agentic Kit updates only the npm package it installed.
7. Observed truth drives status. Parse deja doctor --json --offline, the package on disk, host configuration, and ownership receipts; never infer healthy from process exit alone.
8. Data removal is a separate decision. Wiring, binary, cache, curated notes, and source transcripts are different deletion scopes.
9. Historical recall is untrusted input. Preserve upstream recall framing and never turn recalled instructions into trusted policy.
10. Unknown stays unknown. A malformed doctor response, unavailable host config, or incomplete index is degraded/unknown, not healthy or absent.

Proposed user experience

Setup

Add explicit setup options:

ak setup --with-deja-vu
ak setup --with-deja-vu --deja-vu-mode mcp
ak setup --with-deja-vu --deja-vu-mode auto
ak setup --no-deja-vu

Interactive setup should default to No and explain, before mutation:

• which local transcript stores may be read;
• that a local, unencrypted derived index is written;
• which enabled hosts will receive MCP entries;
• whether session-start hooks/plugins will be added;
• that default redaction is best-effort rather than a secrecy guarantee;
• that no sync/share or embedding endpoint is configured;
• that normal status uses offline doctor mode.

Recommended default after opt-in: mode: "mcp".

Status

Add a concise row and structured JSON facts:

deja-vu  ok    0.16.7 npm-managed · MCP: claude,codex · index current
deja-vu  warn  installed externally · codex wiring missing
deja-vu  warn  npm 0.16.6 installed, 0.16.7 available · sync upgrades it
deja-vu  warn  index stale · sync warms it
deja-vu  info  management disabled

The collector should distinguish:

• absent;
• present and externally managed;
• present and Agentic Kit-owned;
• package update available;
• MCP-only versus auto target per host;
• requested target unavailable on the installed deja-vu version;
• index missing, stale, damaged, or healthy;
• source store missing, empty, unreadable, or parsed-zero;
• doctor/version check unavailable;
• user drift preserved.

Status and Dashboard output must never include transcript text, queries, raw project paths, or recalled content.

Sync

ak sync should:

1. install @vshulcz/deja-vu@latest only when enabled and absent;
2. upgrade only an Agentic Kit-owned npm installation;
3. never call deja update for that npm installation;
4. reconcile target-specific wiring for enabled hosts:
   • Claude: claude-code or claude-auto
   • Codex: codex or codex-auto
   • OpenCode: opencode or opencode-auto
5. invoke upstream wiring with --no-guidance --no-index, because Agentic Kit owns shared guidance and should perform one bounded warmup after all targets converge;
6. remove a superseded owned target before or as part of switching modes;
7. run deja warmup only after initial install, source changes that make the index stale, or an explicit repair plan;
8. verify independently with offline doctor output plus host configuration observations;
9. recollect status and fail if required owned surfaces did not converge.

Repeated sync must be a true no-op.

Removal

Extend uninstall with explicit scopes:

ak uninstall                         # remove Agentic Kit-owned deja wiring
ak uninstall --remove-deja-vu       # also remove the owned npm package
ak uninstall --purge-deja-vu-data   # also delete the derived deja index/data, confirmed
ak uninstall --purge                # include owned package; preserve deja data unless separately requested

Rules:

• Run target-specific deja uninstall only for targets recorded as Agentic Kit-owned.
• Preserve unrelated host configuration and user-modified values.
• Preserve an external binary/plugin and say how it remains installed.
• Remove the npm package only when the install receipt proves Agentic Kit owns it.
• Preserve ~/.cache/deja, XDG notes, policy, exclusions, tombstones, imports, and usage records by default.
• A data purge must resolve and validate exact known paths, present a preview, require confirmation, and never touch source session stores.
• If teardown is incomplete, retain the ownership receipt and return nonzero so recovery remains possible.

Configuration and ownership model

Extend the versioned integration envelope rather than adding another unrelated top-level boolean:

{
  "integrations": {
    "version": 3,
    "tools": {
      "dejaVu": {
        "enabled": true,
        "mode": "mcp",
        "hosts": ["claude", "codex"],
        "indexOnSetup": true
      }
    },
    "ownership": {
      "dejaVu": {
        "install": {
          "method": "npm",
          "package": "@vshulcz/deja-vu",
          "managedBy": "agentic-kit"
        },
        "targets": {
          "claude": "claude-code",
          "codex": "codex"
        }
      }
    }
  }
}

The exact schema can be refined in the ADR update, but it must preserve these distinctions:

• desired enablement;
• recall mode;
• desired host set;
• observed install method;
• package ownership;
• per-host wiring ownership;
• prior/written values or an equivalent upstream-owned target receipt;
• user data ownership, which remains user even when Agentic Kit built the derived index.

Configuration migration must be additive and default existing installations to disabled/unowned.

Proposed architecture

Managed companion adapter

Add a built-in deja-vu lifecycle adapter, for example:

• src/lib/deja-vu.mjs — package/version, binary path, doctor parsing, target capability mapping, index facts;
• src/lib/adapters/deja-vu.mjs — detect/plan/apply/verify/undo;
• a static managed-companion registry if needed so future tools do not require another set of command-specific branches.

Do not add deja-vu to HOST_REGISTRY or PROVIDER_REGISTRY. It consumes host capabilities and projects memory wiring into those hosts.

Lifecycle contract

detect

• read desired config;
• resolve binary and install method;
• read global npm package version from disk;
• parse deja version where needed for external installs;
• parse deja doctor --json --offline;
• inspect enabled-host wiring and upstream wiring.json;
• return normalized facts and diagnostics without writing or refreshing.

plan

• deterministically calculate package, target transition, warmup, verification, and undo operations;
• disclose every host config/hook/plugin mutation;
• produce no operation for disabled or externally owned package updates;
• classify destructive data purge separately.

apply

• install a released npm artifact;
• invoke target-specific upstream install/uninstall commands;
• pass --no-guidance --no-index;
• run one warmup when planned;
• record exact ownership receipts only after successful operations;
• report ok/degraded/failed/skipped plus whether an older artifact remains usable.

verify

• independently re-run offline doctor parsing;
• observe actual host configuration and target state;
• prove expected index state without retrieving or printing user content;
• never trust the apply result as proof.

undo

• reverse dependencies: auto hooks/plugins → MCP wiring → owned package;
• use the exact owned target set;
• preserve user drift and external installations;
• retain receipts after any incomplete undo.

Phased implementation plan

Phase 0 — ADR and domain alignment

• Amend ADR-0016 or add a focused Proposed ADR for managed companion tools.
• Define deja-vu's role relative to Ruflo/AgentDB.
• Define setup trust disclosure, install ownership, wiring ownership, and data-preservation semantics.
• Correct the stale “ADR-0016 is Proposed” text in docs/MANAGED-TOOLS.md.
• Update docs/ddd/integration-management.md and ubiquitous language with “managed companion tool.”

QA gate: ADR status/dates are current; no document claims behavior is implemented yet.

Phase 1 — Detection and normalized facts

• Add npm/global/external install detection.
• Parse upstream version and doctor JSON fixtures.
• Map Agentic Kit host ids to supported deja-vu MCP/auto targets.
• Add structured status facts and human rows.
• Keep collection read-only and offline.

QA gate: malformed, missing, stale, damaged, external, and unsupported cases are fixture-covered and honestly classified.

Phase 2 — Setup and installation

• Add setup flags and persisted opt-in intent.
• Add pre-mutation disclosure.
• Install @vshulcz/deja-vu@latest through the existing managed npm path.
• Wire selected hosts in MCP mode by default.
• Run one warmup with visible progress.
• Verify before recording success.

QA gate: clean-machine setup is hermetic on Linux, macOS, and Windows; a failed install cannot render green or claim ownership.

Phase 3 — Sync, upgrades, and drift repair

• Fold the package into the managed version/drift story.
• Reconcile per-host targets after host enable/disable or recall-mode changes.
• Repair stale/missing owned wiring.
• Warm a stale index only when the plan calls for it.
• Add Dashboard card/banner integration from the same facts.

QA gate: two consecutive syncs cause zero additional writes or process mutations; status, JSON, Dashboard, and plan agree.

Phase 4 — Safe removal and data purge

• Add owned target teardown.
• Add explicit package removal.
• Add separately confirmed derived-data purge.
• Preserve source histories and user-owned/external state.
• Retain receipts on partial failure.

QA gate: install → user drift → uninstall preserves user changes; uninstall on a never-managed machine creates or removes nothing.

Phase 5 — Documentation and proof

• Update README, SETUP, MANAGED-TOOLS, UPGRADING, TROUBLESHOOTING, security/privacy guidance, and uninstall help.
• Add an operator runbook for MCP versus auto mode.
• Add focused verification and full regression evidence.

QA gate: pnpm run check passes and the packed CLI proves setup/status/sync/uninstall under redirected HOME/XDG/npm roots.

Test strategy

Adapter conformance

The deja-vu adapter must pass the shared lifecycle harness:

• detection is read-only;
• planning is deterministic;
• dry-run performs no writes or mutating subprocess calls;
• apply is idempotent;
• verify reports observed truth;
• undo touches only owned targets/values;
• user drift survives;
• malformed/unavailable surfaces degrade honestly.

Installation matrix

Binary state	Wiring state	Expected
absent	none	opt-in setup installs npm package and selected targets
npm, Agentic Kit-owned	healthy	managed and upgradeable
npm, pre-existing	healthy	usable but unowned until explicitly adopted
Homebrew/Go/manual	healthy	external, detectable, never auto-updated/removed
plugin-only	healthy	external plugin fact; no duplicate local wiring
owned package	missing target	sync restores target
owned package	user-modified target	preserve drift and report
owned package	old version	sync upgrades via npm, then verifies wiring
package usable after failed upgrade	old version remains	failed + usable, never green
unsupported target/version	none	degraded/unsupported, no guessed success

Host matrix

• Claude MCP-only and auto.
• Codex MCP-only and auto.
• OpenCode MCP-only and auto.
• Enabled-but-absent host produces no config home.
• Host disabled after prior ownership removes only its owned deja target.
• Switching MCP ↔ auto leaves exactly one intended target.
• Plugin/local wiring coexistence does not produce duplicate recall.

Data and privacy tests

• no transcript text or query reaches status/JSON/Dashboard;
• no source transcript is modified or deleted;
• index warmup uses redirected fixture stores;
• purge refuses broad/unresolved paths;
• default uninstall preserves index, notes, policy, exclusions, tombstones, and imports;
• recalled content remains framed as untrusted;
• failure messages are bounded and path/content-safe.

Acceptance criteria

• deja-vu is represented as an optional managed companion, not a host/provider or AgentDB replacement.
• Existing configurations migrate additively to disabled/unowned deja-vu intent.
• Setup offers an explicit opt-in and defaults to MCP-only mode.
• Setup discloses transcript reads, local index writes, host wiring, and optional auto hooks before mutation.
• Agentic Kit installs the published @vshulcz/deja-vu npm artifact and records ownership only after verified success.
• External Homebrew/Go/manual/plugin installs remain visible but unowned.
• Only enabled/present Agentic Kit hosts are wired.
• --no-guidance --no-index prevents duplicate guidance and repeated per-target index builds; one bounded warmup follows.
• ak status and JSON distinguish presence, ownership, install method, version drift, MCP/auto targets, index health, source health, and degraded/unknown states.
• ak sync --dry-run is non-mutating.
• Repeated ak sync is idempotent and produces no duplicate MCP entries or hooks.
• npm-managed updates use npm; Agentic Kit never calls deja update for them.
• Mode transitions leave exactly the requested per-host wiring.
• Verification observes host config and offline doctor facts independently of apply.
• Default uninstall removes Agentic Kit-owned wiring but preserves the index and all source histories.
• --remove-deja-vu removes only an Agentic Kit-owned npm package after confirmation.
• Data purge is separate, confirmed, exact-path guarded, and cannot delete source transcripts.
• Partial teardown retains ownership receipts and returns nonzero.
• No transcript text, query content, raw recalled content, or credentials appear in status, logs, receipts, or Dashboard output.
• Shared lifecycle conformance, clean-machine, cross-platform, migration, drift, and no-clobber tests pass.
• ADR/document dates and statuses are updated in the same change; docs/MANAGED-TOOLS.md no longer calls Accepted ADR-0016 Proposed.
• pnpm run check passes.

Success measures

1. A new opt-in installation reaches healthy verified state through one ak setup run.
2. A second setup/sync performs zero writes when nothing changed.
3. Claude, Codex, and OpenCode can share one local deja-vu index without duplicate per-host recall wiring.
4. Package upgrade plus wiring verification converges in one sync.
5. MCP-only users receive no automatic historical context injection.
6. Uninstall leaves unrelated host configuration byte-equivalent and preserves user data by default.
7. All degraded conditions retain enough evidence for a specific remediation rather than a generic reinstall.
8. Ruflo/AgentDB project memory remains the curated operational authority; no raw-history mirroring is introduced.

Risks and mitigations

Risk	Mitigation
Duplicate recall or token noise beside Ruflo context	MCP-only default; explicit auto mode; exact target verification
Historical prompt injection	preserve upstream untrusted recall framing; never execute recalled instructions as policy
Secrets or sensitive prose in logs	disclose best-effort redaction limits; keep index local; never surface content in ak
Unencrypted local index	disclose before install; preserve OS permissions; document disk-encryption recommendation
Host config collisions	upstream target-specific no-clobber behavior plus Agentic Kit ownership receipts and independent verification
Two update owners	npm-managed package updated only by ak; external installs disowned
Expensive repeated indexing	target installs use --no-index; one planned warmup; stale-only repair
Upstream doctor/schema drift	versioned parser fixtures; unknown/degraded on unsupported shape
External plugin plus local binary duplication	detect plugin/local wiring and refuse duplicate adoption without an explicit transition
Destructive cleanup ambiguity	separate wiring, package, derived data, notes, and source transcript scopes

Definition of done

This issue is complete when an opted-in user can install, configure, verify, update, repair, and safely remove deja-vu through Agentic Kit; all operations obey the shared lifecycle and ownership contracts; MCP-only remains the default; external installations and user data are preserved; and Ruflo/AgentDB and deja-vu have clearly documented, non-overlapping authority boundaries.