--- name: memory-ingest description: Transform validated knowledge into structured long-term memory. Activate after Bootstrap scan, after Discovery produces validated artefacts, or after architecture insights are available. license: ELv2 compatibility: Works with any filesystem-based AI coding agent metadata: author: gaai-framework version: "1.0" category: cross track: cross-cutting id: SKILL-MEMORY-INGEST-001 updated_at: 2026-04-05 status: stable inputs: - discovery_outputs (validated) - architecture_insights - validated_decisions - project_knowledge - marketing_observation_logs (validated hypotheses, promise drafts — from contexts/artefacts/marketing/**) - strategy_artefacts (validated GTM decisions — from contexts/artefacts/strategy/**) outputs: - contexts/memory/** (any category registered in index.md) - contexts/memory/index.md (updated) --- # Memory Ingest ## Purpose / When to Activate Activate after: - Bootstrap scan produces architecture insights - Discovery produces validated artefacts or decisions - New validated project knowledge needs to be persisted **Only ingest validated knowledge — never raw session output.** --- ## Process **CRITICAL — Anti-Collision Guard (MUST execute before writing any memory file):** Before writing any file under `contexts/memory/**`, check if the target file already exists on disk: - If it does NOT exist → proceed normally. - If it DOES exist → **read the existing file first**. Then decide: - If the existing content covers a **different topic or entity** than what you are about to write → **STOP immediately**, surface the collision to the human, do not proceed. - If the existing content covers the **same topic** and an update is warranted → proceed, but preserve any human edits or prior knowledge that remains valid. Treat this as an **update**, not a replacement. - If the existing content is identical or still valid → skip writing, report "no changes needed". This guard prevents the silent data loss incident of 2026-03-17 where concurrent sessions overwrote memory files. 1. Read new validated knowledge (discovery results, decisions, architecture insights, validated hypotheses, GTM decisions) 2. Read `contexts/memory/index.md` to discover available categories (shared and domain). Classify knowledge into the most appropriate existing category. If no existing category fits, create a new one — name it clearly, create the directory, and register it in `index.md` before writing any file. 3. Create or update corresponding memory files using standard templates 4. Register all new or modified entries in `contexts/memory/index.md` — this is mandatory, not optional. Any file not in the index is invisible to all other memory skills. 5. **Domain dual-index rule:** When ingesting into a domain category (`domains/{domain}/`), also update the domain's own `index.md` (e.g., `domains/content-production/index.md`). Both the master index AND the domain index must reflect the new entry. Failure to update both causes silent drift — the domain sub-agent won't see entries missing from its domain index. 6. **Impact Scan (post-write) (informational — does not block ingestion).** After writing new memory files and updating all indexes (steps 3–5): - Re-read `contexts/memory/index.md` and collect all entries whose `tags` overlap with the tags of the ingested content. - For each matching entry, check whether the ingested content changes or invalidates assumptions described in that file (load the file, compare topic overlap). - List any potentially stale entries in the session output: entry path, reason suspected stale. - **If `index.md` is missing or a referenced file is unreadable:** skip the Impact Scan and note `"Impact Scan skipped: {reason}"` in session output — do not fail the ingestion. 6b. **Architecture file gate (applies ONLY to writes under `contexts/memory/architecture/`).** Before writing or updating any file in that folder: - Read `contexts/rules/memory-architecture.rules.md` in full - Apply the **Content Principle** (§1) — if the content is a code snapshot rather than a conceptual invariant, STOP and reclassify (either rewrite at the invariant level or discard — do not weaken the rule) - Apply the **Verify-Before-Update Protocol** (§2) — load each path in `depends_on.code_paths`, confirm every claim in the content still matches current code; on divergence, escalate (never silent-rewrite) - Populate the attestation fields in frontmatter: `verified_against_commit_sha: <40-char sha>` and `verified_at: ` - Writing an architecture file without running this gate, or writing content copied from a memory-delta without independent code verification, is forbidden 7. **Freshness metadata governance (Tier 1–2 files)** After writing any memory file under `architecture/`, `patterns/conventions.md`, or `project/context.md`, verify that both `depends_on` and `refresh_tier` are present in the file's YAML frontmatter before proceeding. - If both are present → continue. - If either is absent → **add them before this step completes**. Do not exit the skill without freshness metadata on a Tier 1–2 file. - If the code paths are unknown, use the safe fallback: ```yaml depends_on: code_paths: [] decisions: [] epics: [] refresh_tier: 2 ``` Then add a session note: `"[FRESHNESS TODO] {file_path}: depends_on.code_paths not populated — manual enrichment required."` - **All other memory files** (outside the three paths above): `depends_on` is optional. If present, validate that `refresh_tier` is also declared and is a value 1–4. If `refresh_tier` is absent but `depends_on` is present, default to `refresh_tier: 2` and note for review. - Rule reference: `contexts/rules/memory-freshness.rules.md` §3 (which files must declare) and §4 (graceful degradation). 8. Ensure memory files remain structured and minimal --- ## Outputs Memory files created at any registered category path (see `contexts/memory/index.md`). Current categories as of last update: - `contexts/memory/project/` — project-level facts, architecture, constraints - `contexts/memory/decisions/` — governance decisions - `contexts/memory/patterns/` — coding conventions, procedural knowledge - `contexts/memory/ops/` — platform operations, DNS, providers, infra procedures - `contexts/memory/contacts/` — experts and leads identified during Discovery - `contexts/memory/domains/content-production/` — domain-scoped: research AKUs, sources, voice guide, gap analysis for content blueprint - `contexts/memory/index.md` — updated (always, mandatory) - Domain `index.md` — updated when ingesting into a domain (mandatory, see Process step 5) > **Governance rule:** Any new category must be registered in `index.md` before use. Never write a memory file to an unregistered path. --- ## Quality Checks - Knowledge is stored in correct memory category - Memory files remain structured and minimal - Index reflects all active memory - No duplication or raw session data - Only validated knowledge enters long-term memory --- ## Non-Goals This skill must NOT: - Store raw session conversations - Ingest speculative or unvalidated information - Duplicate existing memory entries **No knowledge enters memory without explicit validation. Raw exploration belongs to session memory only.**