# Phase 1 Execution Plan: Transcript -> Note -> Memory

> **Status:** Complete with known environment blockers
> **Owner:** `learning_ai_common_plat`
> **Golden Flow:** LysnrAI transcript -> NoteLett note -> MindLyst memory
> **Primary Leads:** Codex for shared-contract and sequencing work, Saravana for final approval and prioritization

---

## 1. Scope

This phase implements one end-to-end ecosystem flow:

1. a transcript is created in `learning_voice_ai_agent`
2. that transcript is represented as a shared artifact
3. `learning_ai_notes` consumes it and creates or links a note artifact
4. `learning_multimodal_memory_agents` consumes the transcript/note lineage and creates or proposes a memory artifact
5. canonical events and provenance are preserved across the chain

This phase is intentionally narrow. It is the first implementation proof for the shared ecosystem contracts.

---

## 2. Repos In Scope

- [`learning_ai_common_plat`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat)
- [`learning_voice_ai_agent`](/Users/saravana/BytelystAI/learning_ai/learning_voice_ai_agent)
- [`learning_ai_notes`](/Users/saravana/BytelystAI/learning_ai/learning_ai_notes)
- [`learning_multimodal_memory_agents`](/Users/saravana/BytelystAI/learning_ai/learning_multimodal_memory_agents)

Out of scope for this phase:

- ActionTrail replay UI
- auth approvals for the flow
- timeline UI
- marketplace work

---

## 3. Implementation Order

Strict order:

1. harden shared contracts in `learning_ai_common_plat`
2. implement producer side in `learning_voice_ai_agent`
3. implement note consumer/producer in `learning_ai_notes`
4. implement memory consumer/producer in `learning_multimodal_memory_agents`
5. run cross-repo verification and update tracker

Do not start product implementation before contract fields and event names are stable enough for Phase 1.

---

## 4. Shared Contract Tasks

Repo: [`learning_ai_common_plat`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat)

### 4.1 Artifact contract hardening

- [x] finalize the transcript artifact envelope
- [x] finalize the note artifact envelope expectations
- [x] finalize the memory artifact envelope expectations
- [x] define required provenance fields for the flow
- [x] define `artifact.linked` relation usage for transcript -> note and note -> memory

### 4.2 Event taxonomy hardening

- [x] finalize `capture.transcript.created`
- [x] finalize `artifact.created`
- [x] finalize `artifact.linked`
- [x] finalize `memory.entry.created`
- [x] add one canonical example payload per event

### 4.3 Verification/fixture prep

- [x] decide fixture location for Phase 1 examples
- [x] create canonical JSON examples for transcript/note/memory artifacts
- [x] create canonical JSON examples for the 4 phase-1 events

Implementation location:

- [`packages/events/src/ecosystem.ts`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/packages/events/src/ecosystem.ts)
- [`packages/events/src/ecosystem.test.ts`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/packages/events/src/ecosystem.test.ts)
- [`packages/events/fixtures/ecosystem/phase1`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/packages/events/fixtures/ecosystem/phase1)

Commits:

- `76f1b47` `feat(events): add phase1 ecosystem contracts`

---

## 5. Repo Task Breakdown

### 5.1 learning_voice_ai_agent

Repo: [`learning_voice_ai_agent`](/Users/saravana/BytelystAI/learning_ai/learning_voice_ai_agent)

Implementation tasks:

- [x] identify the transcript creation boundary to hook artifact emission
- [x] map transcript output into the shared artifact envelope
- [x] emit `capture.transcript.created`
- [x] attach correlation/session identifiers for downstream consumers
- [x] expose or persist the artifact in a way downstream consumers can access

Verification:

- [x] transcript artifact matches canonical fixture shape
- [x] event payload matches canonical fixture shape
- [x] provenance fields are populated

Commits:

- `3b8298b` `feat(voice): emit phase1 transcript artifacts`
- `79c85ad` `fix(voice): persist transcript event index for phase1`

### 5.2 learning_ai_notes

Repo: [`learning_ai_notes`](/Users/saravana/BytelystAI/learning_ai/learning_ai_notes)

Implementation tasks:

- [x] consume transcript artifact reference or payload
- [x] create a linked note artifact using the shared envelope
- [x] emit `artifact.created`
- [x] emit `artifact.linked`
- [x] preserve provenance to the originating transcript artifact

Verification:

- [x] note artifact matches canonical fixture shape
- [x] link relation is present and correct
- [x] no transcript provenance is lost

Commits:

- `6ffc2f8` `feat(notes): import phase1 transcript artifacts`
- `9ecc7c6` `fix(notes): preserve phase1 transcript event lineage`

### 5.3 learning_multimodal_memory_agents

Repo: [`learning_multimodal_memory_agents`](/Users/saravana/BytelystAI/learning_ai/learning_multimodal_memory_agents)

Implementation tasks:

- [x] consume transcript/note lineage
- [x] create or propose a memory artifact using the shared envelope
- [x] emit `memory.entry.created`
- [x] preserve lineage to transcript and note artifacts

Verification:

- [x] memory artifact matches canonical fixture shape
- [x] lineage points back to upstream artifacts
- [x] event payload matches canonical fixture shape

Commits:

- `63c791f` `feat(memory): import phase1 note artifacts`
- `0f469a9` `fix(memory): preserve phase1 note event lineage`

---

## 6. Recommended Commit Sequence

Use this sequence unless a better dependency split is discovered:

1. `learning_ai_common_plat`
   - contract hardening
2. `learning_ai_common_plat`
   - fixture/examples and tracker updates
3. `learning_voice_ai_agent`
   - transcript artifact + event emission
4. `learning_ai_notes`
   - note artifact + linking
5. `learning_multimodal_memory_agents`
   - memory artifact + lineage
6. `learning_ai_common_plat`
   - final verification/tracker commit

This keeps downstream repos aligned to a stable contract before product work lands.

---

## 7. Verification Commands

The exact commands may evolve by repo, but the evidence should include at least:

### learning_ai_common_plat

- [ ] schema/examples validated locally
- [ ] docs/tracker updated

### learning_voice_ai_agent

- [x] relevant backend or product tests covering transcript creation path
- [x] fixture conformance evidence recorded
      Evidence:
      `python3 -m pytest tests/test_ecosystem_phase1.py -q` passed locally

### learning_ai_notes

- [x] relevant backend/web tests covering artifact creation/linking path
- [x] fixture conformance evidence recorded
      Evidence:
      Windsurf-verified (`623d02c`): 13 focused ecosystem-phase1 tests covering transcript
      artifact import, note creation, `artifact.created`, `artifact.linked`, upstream event
      causation propagation, provenance lineage preservation, and Zod schema conformance
      against `NoteArtifactEnvelopeSchema`, `ArtifactCreatedEventSchema`, and
      `ArtifactLinkedEventSchema` from `@bytelyst/events`.
      Command: `cd backend && npx vitest run` — 22 files passed, 106 tests passed.

### learning_multimodal_memory_agents

- [x] relevant backend tests covering memory creation/proposal path
- [x] fixture conformance evidence recorded
      Current evidence:
      commit `0f469a9` added `src/lib/ecosystem-phase1.test.ts` to assert note-linked
      event causation propagation and persisted latest memory event index; commit `49796b1`
      adds `mindlyst-native/web/.npmrc` (project-local registry), `test:phase1`, and
      fixes the test fixture setup so Vitest can run that path reliably.
      Codex-verified (2026-04-03):
      `/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/node_modules/.bin/vitest run src/lib/ecosystem-phase1.test.ts src/__tests__/api-memory.test.ts`
      Result: 2 files passed, 10 tests passed (`ecosystem-phase1.test.ts`, `api-memory.test.ts`).
      Remaining local-env gap:
      `npm run test:phase1` is still not self-sufficient in this clone because
      `mindlyst-native/web/node_modules/.bin/vitest` is missing.

### Cross-repo

- [x] one end-to-end golden flow walkthrough recorded in the tracker
- [x] commit hashes added for all participating repos
- [x] residual risks captured
- [x] event lineage hardening commits added for downstream repos
      Walkthrough evidence:
      transcript emitted by LysnrAI, note imported by NoteLett, and memory proposed by MindLyst
      under `/tmp/bytelyst-phase1-walkthrough.qzzwch`
      with persisted event chain:
      `evt_capture_e913dd681aba -> evt_note_created_cced1442727e -> evt_note_linked_c3d477dfd0c4 -> evt_memory_9a3ebd9c67ca`

---

## 8. Done Criteria

This phase is done only when all of the following are true:

- [x] transcript artifact exists in canonical shape
- [x] note artifact exists in canonical shape
- [x] memory artifact exists in canonical shape
- [x] required phase-1 events are emitted in canonical form
- [x] provenance and lineage are preserved
- [x] downstream event traces now preserve upstream causation where the latest event index exists
- [x] tracker has commit links for all participating repos
- [x] residual gaps are documented
- [x] one manual end-to-end walkthrough proves the artifact/event handoff on disk

---

## 9. Known Risks

1. Product repos may have different persistence models that make the artifact handoff uneven.
2. Event emission may be easier than downstream retrieval, so transport or lookup assumptions must stay explicit.
3. Memory creation may need a “proposed” intermediate state rather than immediate durable creation.
4. If the phase-1 event set changes mid-implementation, product repos can drift quickly.

---

## 10. Next Step After Phase 1

If this flow succeeds, the next recommended implementation flow is:

- FlowMonk plan -> ChronoMind routine -> EffoRise habit

Phase 1 closeout decision:

- `complete-with-known-env-blockers`

The implementation and runtime handoff are complete.
Remaining issues are clone-local package runner/setup gaps, not contract or flow gaps.

That would validate a second shared seam: planning/time/habits rather than capture/knowledge/memory.
