Memory Sync

Wingman Memory Sync

memory-sync writes the smallest useful memory update after meaningful work. It chooses the owning body for each memory item before writing.

Storage Roles

brief.md / domains/ = current projection, current binding truth bodies
history/events/     = event log, historical event bodies
history indexes     = projection indexes for historical lookup
context.md          = hot cache, active work state and short pointers

Authority order:

brief.md current Project Decisions
> domains/ current truths
> context.md hot working state
> history/ past events and evidence

Current truth says what future agents must obey now. History explains what changed and why. Context carries only active work state and short pointers.

Gate

Apply these gates before reading or writing memory:

1. If the user opts out of memory for this work, stop without reading or writing memory.
2. If .wingman/memory/ is missing, ordinary completion does not use memory-sync. If sync was explicitly requested, report that repository memory is disabled and memory-setup is the explicit enable path.
3. If .wingman/memory/ exists but .wingman/memory/brief.md or .wingman/memory/context.md is missing, stop before writing, report the missing core entry files, and suggest memory-setup. Do not repair from memory-sync.
4. Continue only when both brief.md and context.md exist.

Before reporting meaningful coding, documentation, configuration, product, or operational work as complete in a repository where memory is enabled, run the routing checks below. If a write route qualifies, sync memory before saying the work is done unless the user opted out.

Ownership Routing

Classify each memory item into one of these routes:

Use IGNORE for typo-only edits, formatting-only edits, rename-only cleanup, isolated visual tweaks, obvious local implementation details, and failed attempts with no reusable lesson.

A task may write more than one route, but each route needs its own reason. When current truth and history are both written, current truth owns the binding rule and history owns the change narrative.

Single Owner Body

Each durable memory item has one owning body:

• current binding rule body: brief.md or domains/;
• historical event body: history/events/;
• historical lookup entry: history/index.md, history/domains/, history/topics/, or history/months/;
• hot working state or pointer: context.md.

Short summaries and pointers are valid. Full duplicated rule bodies, event narratives, evidence, reasoning, or debugging paths are not valid.

Write Flow

1. Apply the Gate.
2. Route each memory item with Ownership Routing.
3. If every item is IGNORE, write nothing and report the threshold that blocked writing.
4. Write CURRENT_TRUTH before HISTORY_EVENT when both are needed.
5. Write HISTORY_EVENT only when the event has durable trace value beyond the current rule.
6. Write CONTEXT_POINTER only for hot state or immediate continuation.
7. Update history projections only for new or changed history events.
8. Report changed memory files or the route that blocked writing.

Current Truth

Write current truth when future agents must obey the result or would otherwise need old logs to avoid a semantic mistake.

Use brief.md for project-wide decisions: global conventions, cross-domain rules, architecture choices, repository policies, memory policy, and project-wide agent behavior.

Use domains/ for one-domain rules: business rules, API contracts, canonical fields, field meanings, state flow, enum mapping, permissions, routing, money, quotas, lifecycle, product invariants, operational procedures, or recurring debugging conclusions.

Before writing current truth:

1. Read brief.md.
2. Use the Domain Registry to choose brief.md or a domain file.
3. Inspect same-subject current entries when practical.
4. Verify evidence from user direction, existing memory, docs, schema, tests, accepted specs, or intentional implementation behavior.
5. If two current entries conflict and no updates or extends relation resolves them, stop and ask which rule is valid.

Use stable identity:

• ID: mem:<domain>:<subject-slug>.
• Subject: stable dotted subject such as order.status.meaning.
• Status: current | superseded | deprecated | candidate.
• Relation: updates <id> | extends <id> | derived_from <id-or-path> | None.
• Confidence: confirmed | implementation-backed | inferred.

Only Status: current entries are binding. Inferred entries start as candidate unless confirmed by user, spec, schema, test, or intentional implementation contract.

When replacing a rule, mark the old entry superseded or deprecated and point to the replacement. When extending a compatible rule, keep both current and link with extends.

Read references/templates.md before using the default current truth template.