# v8.4 Agent Identity Continuity (Engram-Native) Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Add an Engram-native identity continuity system that helps agents preserve stable identity signals across resets, compaction, and long-running operation without relying on external project-specific conventions.

**Architecture:** Implement a dedicated identity continuity layer with three parts: (1) recovery anchor documents, (2) continuity incident logging + audit workflows, and (3) budgeted identity injection controls. Keep all features generic, optional, and fail-open. Never modify OpenClaw session files or pointers; this plan is strictly within plugin-safe boundaries.

**Tech Stack:** TypeScript, existing Engram storage/orchestrator/tools/cli modules, markdown+YAML memory store, existing compounding and shared-context subsystems, node:test.

---

## Execution Status

- [x] Task 1 complete (`feat/v8.4-identity-continuity-config-slice` / PR slice A1)
- [x] Task 2 complete (`feat/v8.4-identity-continuity-storage-slice` / PR slice A2)
- [x] Task 3 complete (`feat/v8.4-identity-anchor-tools-slice` / PR slice A3)
- [x] Task 4 complete (`feat/v8.4-continuity-incident-workflow-slice` / PR slice A4)
- [x] Task 5 complete (`feat/v8.4-continuity-audit-slice` / PR slice A5)
- [x] Task 6 complete (`feat/v8.4-identity-injection-budget-slice` / PR slice A6)
- [x] Task 7 complete (`feat/v8.4-task7-improvement-loop-register` / PR slice A7)
- [x] Task 8 complete (`feat/v8.4-task8-docs-templates` / PR slice A8)

## Design Constraints (Non-Negotiable)

1. **Open-source safe:** No user-specific assumptions, account schemas, or host-specific paths.
2. **Fail-open:** Any identity continuity failure must not break baseline recall/extraction.
3. **Budget-safe:** Identity context injection must be bounded and observable.
4. **No session pointer manipulation:** Plugin must not edit OpenClaw session files/pointers.
5. **Config-gated rollout:** New behavior disabled by default except lightweight diagnostics.

## Functional Requirements

### R1: Recovery Anchor Artifact
- Introduce a structured identity anchor artifact (`identity-anchor.md`) under memory storage.
- Purpose: capture stable identity traits, communication preferences, operating principles, and continuity notes.
- Distinct from normal prompt-time recall; used primarily for recovery/continuity operations.

### R2: Continuity Incident Artifact
- Add append-only continuity incident records with lifecycle states (`open`, `closed`).
- Each incident must capture: trigger time window, observed symptom, suspected cause, applied fix, verification result, preventive rule.
- Records are auditable and immutable except lifecycle-state transitions.

### R3: Continuity Audit Workflow
- Add weekly/monthly continuity audit outputs with a deterministic template.
- Include drift checks (identity changes), stale rule detection, and one next hardening action.
- Integrate with compounding summaries where possible.

### R4: Identity Injection Budgeting
- Add explicit char/token budget controls for identity-context injection.
- Add mode controls:
  - `recovery_only` (default)
  - `minimal`
  - `full`
- Ensure identity context never crowds out core recall sections under constrained budgets.

### R5: Improvement Loop Register
- Add a generic recurring-improvements register artifact (cadence, purpose, status, kill condition, last reviewed).
- Enable agent+operator visibility into which continuity loops are active vs stale.

### R6: Human-Confirm Safety Hooks
- For any operation classified as high-risk continuity action, expose recommendation + checklist only.
- Do not execute destructive or session-wiring actions automatically.

## Non-Goals

1. No direct backup transport implementation to cloud providers in this slice.
2. No OpenClaw core changes (separate blocked plan already exists).
3. No automatic personality rewrites based on transient short-term signals.

## Task 1: Add identity continuity config surface

**Files:**
- Modify: `src/types.ts`
- Modify: `src/config.ts`
- Modify: `openclaw.plugin.json`
- Test: `tests/config-identity-continuity.test.ts`
- Docs: `docs/config-reference.md`

**Steps:**
1. Add flags:
   - `identityContinuityEnabled` (default `false`)
   - `identityInjectionMode` (`recovery_only|minimal|full`, default `recovery_only`)
   - `identityMaxInjectChars` (bounded non-negative)
   - `continuityIncidentLoggingEnabled` (default `true` when identity continuity enabled)
   - `continuityAuditEnabled` (default `false`)
2. Add parser clamps and zero-safe semantics.
3. Add config contract tests.

## Task 2: Implement identity continuity storage manager

**Files:**
- Create: `src/identity-continuity.ts`
- Modify: `src/storage.ts`
- Test: `tests/identity-continuity-storage.test.ts`

**Steps:**
1. Add typed read/write helpers for:
   - `identity/identity-anchor.md`
   - `identity/incidents/YYYY-MM-DD-<id>.md`
   - `identity/audits/weekly/YYYY-WW.md`
   - `identity/audits/monthly/YYYY-MM.md`
   - `identity/improvement-loops.md`
2. Enforce append-only semantics for incidents with explicit close transition API.
3. Add malformed-file fail-open parsing behavior.

## Task 3: Add recovery anchor tooling

**Files:**
- Modify: `src/tools.ts`
- Modify: `src/orchestrator.ts`
- Test: `tests/tools-identity-anchor.test.ts`
- Docs: `docs/api.md`, `docs/operations.md`

**Steps:**
1. Add tools:
   - `identity_anchor_get`
   - `identity_anchor_update`
2. Add conservative update behavior (section-aware merge, not destructive overwrite).
3. Ensure anchor updates are audited in trace logs.

## Task 4: Add continuity incident workflow

**Files:**
- Modify: `src/tools.ts`
- Modify: `src/cli.ts`
- Test: `tests/continuity-incidents.test.ts`
- Docs: `docs/operations.md`

**Steps:**
1. Add tools:
   - `continuity_incident_open`
   - `continuity_incident_close`
   - `continuity_incident_list`
2. Add CLI commands:
   - `openclaw engram continuity incidents`
   - `openclaw engram continuity incident-open`
   - `openclaw engram continuity incident-close`
3. Validate immutable fields and required closure fields.

## Task 5: Add continuity audit generator

**Files:**
- Modify: `src/tools.ts`
- Modify: `src/compounding/engine.ts`
- Test: `tests/continuity-audit.test.ts`
- Docs: `docs/compounding.md`

**Steps:**
1. Add `continuity_audit_generate` tool with weekly/monthly modes.
2. Generate deterministic audit skeleton + summary from available signals.
3. Link audit outputs into compounding weekly synthesis section (if enabled).

## Task 6: Add identity injection budgeting and mode gating

**Files:**
- Modify: `src/orchestrator.ts`
- Modify: `src/recall-state.ts`
- Test: `tests/identity-injection-budget.test.ts`
- Test: `tests/recall-mode-gating.test.ts` (extend for identity modes)
- Docs: `docs/architecture/retrieval-pipeline.md`

**Steps:**
1. Add identity continuity section assembly in recall pipeline.
2. Apply mode behavior:
   - `recovery_only`: inject only when explicit recovery/continuity intent detected.
   - `minimal`: inject compact identity signals.
   - `full`: inject larger structured block under cap.
3. Enforce cap-after-filter and section priority invariants.
4. Add telemetry fields for injected chars and truncation state.

## Task 7: Add improvement-loop register support

**Files:**
- Modify: `src/identity-continuity.ts`
- Modify: `src/tools.ts`
- Test: `tests/improvement-loop-register.test.ts`
- Docs: `docs/operations.md`

**Steps:**
1. Add structured register helpers and validation for required fields.
2. Add tools:
   - `continuity_loop_add_or_update`
   - `continuity_loop_review`
3. Add stale-loop detection signal in audit generation.

## Task 8: Documentation and templates

**Files:**
- Create: `docs/identity-continuity.md`
- Modify: `docs/README.md`
- Modify: `README.md`
- Modify: `CHANGELOG.md`

**Steps:**
1. Document all new artifacts and safety boundaries.
2. Provide generic templates for identity anchor, incidents, and audits.
3. Document rollout recommendations by risk tier.

## Verification Checklist

1. `npm run check-types` passes.
2. `npm test` passes.
3. `npm run preflight:quick` passes.
4. Disabled-path behavior remains baseline-equivalent.
5. Identity injection never exceeds configured caps.
6. Incident artifacts are append-only except close transition.
7. No code path writes or mutates OpenClaw session pointers/files.

## Rollout Plan

1. PR A: config + storage + tests.
2. PR B: anchor + incidents tools/CLI.
3. PR C: audit + improvement loop register.
4. PR D: injection mode/budget integration + docs + hardening gate.
