/org-memory-synthesis — Org-Memory Synthesis

Org-memory ($OACP_HOME/org-memory/) is the cross-project SSOT that the OACP session-init hook auto-loads. It drifts if events accumulate unfolded and topical files (decisions.md, rules.md) aren't curated. This skill does the full 3-file pass — synthesis then audit — so the curated layer stays trustworthy.

When to use

Invoke this skill when:

• The user asks whether org-memory is current
• A wrap-up / housekeeping flow needs to fold recent events
• Cross-file inconsistency or stale entries surface during another task
• An upstream skill hands off the org-memory pass

Files & paths

recent.md header carries <!-- Last event folded in: <filename> --> — use it to scope incremental synthesis cheaply. OACP_HOME defaults to $HOME/oacp per the OACP CLI; check the workspace marker if unsure.

Setup

Resolve the workspace and fail fast if org-memory isn't initialized:

OACP_ROOT="${OACP_HOME:-$HOME/oacp}"
test -d "$OACP_ROOT/org-memory" || {
  echo "ERROR: org-memory not found. Run: agent-memory org init --home \"$OACP_ROOT\"" >&2
  exit 1
}

Synthesis flow

1. Scope the work

List event filenames newer than the marker in recent.md. Filenames are lex-sortable (YYYYMMDD-HHMMSS- prefix), so awk '$0 > m' is the comparison:

OACP_ROOT="${OACP_HOME:-$HOME/oacp}"
RECENT="$OACP_ROOT/org-memory/recent.md"
EVENTS_DIR="$OACP_ROOT/org-memory/events"

MARKER=$(command grep -m1 "Last event folded in:" "$RECENT" \
  | sed -E 's/.*Last event folded in:[[:space:]]+([^[:space:]]+).*/\1/')

if [ -z "$MARKER" ]; then
  echo "WARN: no marker in $RECENT header; listing ALL events (full pass)" >&2
  command ls "$EVENTS_DIR" | sort
else
  command ls "$EVENTS_DIR" | sort | awk -v m="$MARKER" '$0 > m'
fi

• Empty output → org-memory is current; jump to Step 7 (audit-only pass).
• Missing marker (older recent.md) → script lists all events and warns; do a full pass and tell the user the read cost.

2. Batch-read new event bodies

One Bash call. Read each event's body so you have enough context to categorize:

cd $OACP_HOME/org-memory/events && for f in <newline-separated names from step 1>; do echo "=== $f ==="; command tail -n +9 "$f"; echo; done

(tail -n +9 skips the YAML frontmatter — frontmatter is for routing, the body is what gets folded. Adjust if your event files use a different frontmatter length.)

3. Categorize each event

The event's type: frontmatter field drives placement:

Cross-repo signal: count distinct repos in the event's related: field. 3+ is the promotion threshold. Skill-specific rules (those that only affect one skill's flow) stay in recent.md Standing Rules only — promoting them adds rules.md noise without cross-repo benefit.

4. Propose a 3-file diff to the user

Present as three sections — recent.md, decisions.md, rules.md. For each promotion, give a one-line rationale tying it to the 3+ pattern threshold, cross-repo signal, or convention class. Note recent.md line-budget impact so it stays under 150.

5. Apply edits

Use the Edit tool. Place new decisions.md entries at the top of the file under a ## YYYY-MM-DD heading so newest-first order is preserved (Step 7D will re-sort if not).

6. Update the markers

Two header lines in recent.md:

• <!-- Last event folded in: <newest event filename from step 1> -->
• <!-- Last curated: YYYY-MM-DD by <who> -->

A dropped marker forces the next pass to re-scan all events, defeating the incremental design.

7. Audit pass — ALWAYS run after synthesis

Six checks, in order. The audit catches what synthesis alone misses.

A. Cross-file consistency. For items appearing in both recent.md and a curated file (e.g., product structure, pricing, paths, version numbers), compare key facts. Surface mismatches — they usually mean one file fell behind.

B. Supersession check. Scan decisions.md for Supersedes X annotations. For each X, verify X is also marked as superseded with a pointer back. Asymmetric supersession reads as if both are active.

C. Stale-status check. Find entries with status claims like "Filed #N", "Pending review", "Q1 target". For GitHub issue refs where the repo can be inferred, verify state:

gh issue view <N> --repo <owner>/<repo> --json state,closedAt,updatedAt

(Runtimes that sandbox the shell may need to allow gh for this step — configure that in your runtime's permissions, not in the skill body. If gh auth is missing, report the unchecked refs rather than inventing status.) Annotate stale claims inline rather than removing them, e.g. Status: #15 still OPEN P3, not actioned.

D. Chronological order in decisions.md. Section headers must run newest-first, top-to-bottom (new entries go at the top, so the freshest decisions are the first thing a reader — or a session-init load — sees). Run the mechanical check — don't self-report:

command grep -nE '^## 20' $OACP_HOME/org-memory/decisions.md \
  | awk '{print $2}' | sort -rc
# Exit 0 = order is correct (descending). Non-zero = re-sort needed.

If sort -rc reports a disorder, re-sort with one Edit operation. The mechanical check is the verification — never substitute self-reporting. (A real false-clean was caught with this exact check when a newly-folded section was placed at the wrong end of an otherwise-ordered file.)

E. Category drift. Conventions filed under decisions.md should move to rules.md, and vice versa. Decisions are architectural calls; rules are standing conventions. If unclear, default to leaving where the historical event-author put it.

F. Migration leftovers. Content duplicated with another memory tree (e.g., content owned by a domain-specific memory store) should be trimmed to a single pointer.

8. Surface findings, apply, ask

Apply uncontroversial fixes directly (annotations, chronological re-sort, removing strict duplications). Pause and ask on judgment calls — pricing/status conflicts where the truth isn't obvious from local context.

9. Suggest commit (don't auto-commit)

Typical commit message:

org-memory: synthesize <N> events + audit pass

- <N> events folded into recent.md (<M> to decisions.md, <K> to rules.md)
- <audit findings summary>

Let the user run the commit; the skill never commits automatically.

Anti-patterns

• Don't delete superseded entries — annotate. History is load-bearing for understanding why a decision changed. Add **Superseded by YYYY-MM-DD <title>.** inline.
• Don't promote skill-specific rules to rules.md. Keep them in recent.md Standing Rules.
• Don't auto-commit. The user reviews and decides commit timing.
• Don't touch sibling memory trees (project-scoped memory directories). Read-only from this skill's perspective.
• Don't drop the marker. It's the cheapest performance optimization in this flow.
• Don't replace the Step 7D sort -rc check with a prose claim. Self-reported "chronological order looks fine" misses real false-cleans. Run the mechanical check.

Workarounds

• Use command ls, command grep, command tail to bypass shell aliases (ls → eza, grep → rg).
• gh issue view in Step 7C may need a runtime sandbox bypass — configure in the runtime, not inline.
• recent.md target ≤150 lines; decisions.md and rules.md grow over time — trim via annotation, not deletion.

Notes

• The skill operates on $OACP_HOME/org-memory/ only. It never edits sibling project-scoped memory.
• shared/INTENT.md is the source of truth for runtime-agnostic behavior.

Learned from runs