Trajectory and patch trail

Trajectory memory¶

Trajectory memory is a deterministic process narrative derived from the audit event core. It complements governed memory cards: cards hold durable repository facts; trajectories hold bounded edit-cycle timelines (declare → check → verify → receipt → optional Patch Trail).

codeclone memory trajectory rebuild --root .

Architecture¶

flowchart TB
    subgraph Finish["Change controller (MCP finish)"]
        FIN[finish_controlled_change]
        PT[compute_patch_trail]
        AUDE[patch_trail.computed audit event]
        FIN --> PT --> AUDE
    end

    subgraph Audit["Audit SQLite"]
        EC[event_core_json per workflow]
    end

    subgraph Project["Trajectory rebuild"]
        PRJ[projector trajectory-v3]
        PTP[patch_trail_projector]
        QLT[quality + anomaly analytics]
        SUP[supersede stale rows]
    end

    subgraph Store["Engineering Memory SQLite"]
        TRJ[memory_trajectories + steps]
        PTR[memory_trajectory_patch_trails]
        JOB[memory_projection_jobs]
    end

    subgraph Read["Read surfaces"]
        GR[get_relevant_memory.trajectories]
        QEM[query_engineering_memory trajectory_*]
        DASH[dashboard + agents + anomalies]
        EXP[JSONL export v2]
    end

    AUDE --> EC
    EC --> PRJ
    EC --> PTP
    PRJ --> QLT
    PRJ --> TRJ
    PTP --> PTR
    PRJ --> SUP
    TRJ --> GR
    TRJ --> QEM
    QLT --> DASH
    PTR --> GR
    PTR --> QEM
    TRJ --> EXP
    PTR --> EXP
    JOB -.->|enqueue_when_stale| Project

Module ownership:

Config ([tool.codeclone.memory])¶

Requires audit_enabled=true and a readable audit DB for rebuild input.

CLI¶

codeclone memory trajectory status --root .
codeclone memory trajectory rebuild --root .
codeclone memory trajectory list --root . --limit 20
codeclone memory trajectory show TRAJ_ID --root .
codeclone memory trajectory search "recover stale intent" --root .
codeclone memory trajectory export \
  --root . \
  --profile agent-change-control-v1 \
  --out .codeclone/trajectories.jsonl \
  --force

Export profiles (schema contracts): agent-change-control-v1, agent-memory-retrieval-v1, agent-recovery-v1, agent-security-hardening-v1. Export row schema version is 2 (TRAJECTORY_EXPORT_SCHEMA_VERSION). Each row includes:

Rebuild supersedes older projection rows for the same workflow (one canonical trajectory per workflow_id in export). Legacy audit rows without path facts in frozen event core are supplemented deterministically from stored audit payloads during projection. Changing profile shape requires a profile version bump.

MCP retrieval¶

get_relevant_memory adds trajectories[] beside records[] when path subjects match (declare scope_paths, check changed_files, or untouched_in_declared). When a stored Patch Trail exists for a matched trajectory, each preview includes patch_trail_summary (counts, digest, verification status). With detail_level=full, the top-ranked trajectory also surfaces patch_trail_summary at the response root. Compact retrieval omits that root duplicate; the summary remains on the trajectory preview.

query_engineering_memory(mode=trajectory_get) returns patch_trail when persisted and always uses full detail, including quality_contract. List/search previews retain headline quality, complexity, and anomaly counts.

Trajectory rebuild (memory trajectory rebuild / MCP manage_engineering_memory(action=rebuild_trajectories)) synthesizes Patch Trail from audit event cores (intent.declared, intent.checked, verify events) and stores it in memory_trajectory_patch_trails. Trajectory digest (trajectory-v2 and later) incorporates patch_trail_digest when present. The active trajectory-v3 digest additionally incorporates the persisted quality score and records the primary agent as an agent subject.

Scoped ranking adds a small boost when query scope paths intersect untouched_in_declared paths from the stored Patch Trail.

query_engineering_memory modes:

Filter: filters.include_routine=true on trajectory_search includes single-event run:* analysis workflows.

Evidence kind trajectory links memory records to trajectories; human approve still required for agent drafts.

See Trajectory labels for labels and Trajectory quality and passport for scoring, anomalies, dashboards, and IDE passport semantics.

Enterprise boundary (export)¶

Community CodeClone writes local JSONL only — no remote API, upload, or training pipeline. Corporate policy packs, signing, approval workflows, and dataset registry are out of scope unless explicitly requested.

Refs: codeclone/memory/trajectory/rebuild_workflow.py, codeclone/memory/trajectory/export.py, tests/test_memory_trajectory_*.py, tests/test_audit_event_core_v2.py.