# Wake-Up Packet
## Goal
A wake-up packet is a stable, compact, explainable context bundle that helps an AI client quickly recover the most important developer, project, and task context without scanning the full vault.
It is the first structured output that turns `spool` from a note retriever into a cross-AI memory gateway.
## Design Principles
1. local-first and deterministic
2. explainable over magical
3. derived from trusted sources when possible
4. sensitivity-aware by default
5. shaped for multiple AI clients without changing the underlying meaning
## Non-Goals
Wake-up packets are not:
- a replacement for full note retrieval
- a raw event ledger export
- a long-form memory compression format
- a hidden policy engine
They should be treated as a fast-start layer that points the client toward the right durable context.
## Packet Types
The initial version supports two packet profiles:
1. developer wake-up packet
2. project wake-up packet
A future version may add:
- repo-session packet
- task handoff packet
- incident response packet
## Packet Contract
A wake-up packet should be represented as a structured object with these top-level fields:
```json
{
"version": "wakeup.v1",
"generated_at": "2026-04-08T15:00:00Z",
"target": "claude",
"profile": "project",
"query": {
"task": "design MCP interface",
"cwd": "/Users/long/Work/spool",
"files": ["src/app.rs"]
},
"identity": {},
"working_style": {},
"active_context": {},
"priorities": [],
"constraints": [],
"decisions": [],
"incidents": [],
"recommended_notes": [],
"provenance": {},
"policy": {}
}
```
## Top-Level Fields
### `version`
Packet schema version. Start with `wakeup.v1`.
### `generated_at`
UTC timestamp for traceability and stale-context detection.
### `target`
The intended AI client or shaping profile.
Suggested initial values:
- `claude`
- `codex`
- `opencode`
- `generic`
### `profile`
The packet intent.
Suggested initial values:
- `developer`
- `project`
### `query`
The routing input that caused the packet to be generated.
Fields:
- `task`
- `cwd`
- `files`
- optional `modules`
- optional `scenes`
### `identity`
Stable identity facts that help a client orient quickly.
For a developer packet, examples include:
- role
- primary languages
- preferred collaboration style
- default review style
For a project packet, examples include:
- `project_id`
- project name
- repository roots
- major domains
- architecture summary
### `working_style`
Durable preferences that change how the client should behave.
Examples:
- prefer terse replies
- explain architectural changes before coding
- avoid destructive actions without confirmation
- prefer local-first and explicit provenance
This field should prioritize `memory_type: preference` and `memory_type: workflow` notes.
### `active_context`
The current project situation relevant to the query.
Examples:
- current phase or initiative
- active migration or refactor
- known open gaps
- current stack or architectural boundary
This field should prioritize `memory_type: project` and `memory_type: constraint` notes.
### `priorities`
A short ordered list of the most important things to optimize for right now.
Examples:
- keep Obsidian as curated truth
- expose stable tool interface before daemonizing
- avoid mixing raw ledger events with curated memory
### `constraints`
Hard requirements or boundaries that should shape later actions.
Each item should follow this structure:
```json
{
"title": "Obsidian remains curated source of truth",
"summary": "Raw captured session memory must not be written directly into curated notes.",
"sensitivity": "internal",
"source": "10-Projects/spool/Constraints.md"
}
```
This field should prioritize `memory_type: constraint` notes and source-of-truth notes.
### `decisions`
Important accepted decisions relevant to the current query.
Each item should include:
- decision title
- short rationale
- reversal condition if known
- source note or ADR
This field should prioritize `memory_type: decision` notes.
### `incidents`
Important failures or pitfalls that should change how the client proceeds.
Each item should include:
- incident summary
- consequence
- prevention or caution
- source note
This field should prioritize `memory_type: incident` notes.
### `recommended_notes`
The highest-value notes the client should fetch or inspect next.
Each item should include:
- `path`
- `title`
- `memory_type`
- `why_relevant`
- `score`
This field bridges wake-up packets and normal retrieval.
### `provenance`
Explains where packet content came from.
Suggested shape:
```json
{
"derived_from": [
{
"path": "10-Projects/spool/Project Overview.md",
"source_of_truth": true,
"memory_type": "project"
}
],
"selection_basis": [
"project_id matched spool",
"memory_type constraint boosted score",
"source_of_truth boosted retrieval"
]
}
```
### `policy`
Summarizes output filtering that affected the packet.
Suggested fields:
- `max_sensitivity_included`
- `redactions_applied`
- `suppressed_note_count`
- `policy_mode`
This should make the packet explainable when later policy controls become stricter.
## Source Selection Rules
Wake-up packets should not summarize the whole vault. They should be assembled from a constrained candidate set.
Recommended selection order:
### Project packet
1. route project using `cwd`
2. scan only configured project `note_roots`
3. score notes using the existing retrieval engine
4. hard-filter by packet profile and sensitivity policy
5. promote top notes into packet sections by `memory_type`
6. keep only a small number of entries per section
### Developer packet
Developer packets should not depend only on project routing.
They should draw from a merged candidate set:
1. global developer roots such as `00-Identity`, `20-Areas`, `30-Workflows`
2. optionally, the matched project's `note_roots` for project-scoped preferences or constraints
3. the same scoring core, followed by packet-profile filtering and sensitivity policy
This keeps the builder aligned with the current routing and ranking core while allowing durable cross-project preferences to appear in developer-oriented packets.
Suggested first-pass limits:
- `working_style`: up to 5 items
- `priorities`: up to 5 items
- `constraints`: up to 5 items
- `decisions`: up to 5 items
- `incidents`: up to 3 items
- `recommended_notes`: up to 8 items
## Section Mapping Heuristic
Initial mapping from `memory_type` to packet section:
- `preference` -> `working_style`
- `workflow` -> `working_style`
- `project` -> `active_context`
- `constraint` -> `constraints`
- `decision` -> `decisions`
- `incident` -> `incidents`
- `pattern` -> `recommended_notes`
- `session` -> excluded by default unless packet profile is session-oriented
## Sensitivity Behavior
Before a full policy engine exists, wake-up generation should follow conservative defaults:
- `public`: allowed
- `internal`: allowed
- `confidential`: include only if strongly relevant and avoid verbatim detail by default
- `secret`: excluded from packet body by default
Even when a note is excluded, the packet may record that filtering happened through `policy.suppressed_note_count`.
## Client Shaping
The underlying packet meaning should stay stable, but rendering may vary slightly by target.
### `claude`
Optimize for:
- concise narrative fields
- explicit constraints and working style
- stronger provenance cues
### `codex`
Optimize for:
- file-aware project context
- direct next-note suggestions
- compact action-oriented bullets
### `opencode`
Optimize for:
- neutral machine-readable fields
- predictable section ordering
- low narrative overhead
### `generic`
Return the canonical packet without client-specific wording.
## Output Shapes
The canonical representation should be JSON-first.
Recommended render modes later:
1. `json`: authoritative packet object
2. `markdown`: readable handoff summary
3. `prompt`: compact AI-ready briefing
## Relationship To Retrieval
Wake-up packets do not replace `get` or `explain`.
Instead:
- `wakeup` gives the client a fast, stable orientation bundle
- `get` returns broader context excerpts
- `explain` shows why routing and ranking worked
This means wake-up packet generation should reuse the same routing and candidate scoring core where possible.
## CLI Direction
A future CLI shape should look like:
```bash
spool wakeup \
--config spool.toml \
--task "design MCP interface" \
--cwd /abs/path/to/repo \
--files src/app.rs \
--target claude \
--profile project \
--format json
```
## Implementation Guidance
The first implementation should:
1. reuse the current route + scan + score pipeline
2. define a packet builder separate from renderers
3. keep packet fields explicit instead of freeform summaries
4. record provenance for every promoted section item
5. keep sensitivity handling centralized rather than scattered across renderers
## Open Questions
1. should `active_context` be a structured object or an ordered list of memory items?
2. should packet shaping happen before or after policy filtering?
3. should `recommended_notes` include only curated notes, or ledger-derived memory objects later?
4. when ledger exists, how should packet generation balance curated truth versus recent raw signals?
## Recommended Next Follow-Up
After this schema is accepted:
1. define `memory_wakeup` in the MCP surface
2. add packet types to the Rust domain model
3. add `wakeup` as a stable CLI subcommand
4. add target-aware packet renderers
5. add policy-aware suppression reporting