memory-ingest

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-05T00:00:00.000Z","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: <ISO 8601 timestamp>
   • 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:

     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.