---

name: ai-context-layer description: "Designs cross-session agent memory: point-in-time facts, consolidation, tenant isolation. Use when auditing user memory or Mem0/Zep. Not for repo context (dev-context-engineering)." compatibility: Portable core. Works on Claude Code and Codex. version: "1.6" last_validated: 2026-09-27

App Context Layer

Design and review the application layer that selects, assembles, grounds, and learns from context for a product surface. Keep operational truth in tools, APIs, SQL, or a system of record; use derived memory only for durable facts or preferences with provenance, retention, and correction paths. This skill covers architecture and runtime contracts, not repo instruction files or prompt wording.

Quick Reference

Question	Default	Load when needed
Where should operational truth live?	Tools, APIs, SQL, or system-of-record services	context-layer-detail
Is the problem retrieval or context assembly?	Use RAG for corpus retrieval; use this skill when personalization, relationships, action context, or surface bundles change the answer	ai-rag, context assembly
Is graph worth it?	Only when relationship traversal changes the answer	graph and relationship layer
Which architecture pattern fits?	Select the smallest pattern that meets tenancy, freshness, evidence, and budget needs	patterns catalog, reference architectures
Relational, graph, or vector storage?	Use the owning database design matrix alongside the context decision	storage paradigm selection
Is the scenario known (personal assistant, support/CRM, coding agent, multi-agent, regulated KB, code hub, incident, procedural, voice, analytics, on-device)?	Load its playbook first: R1–R7 defaults, upgrade trigger, acceptance tests	memory-scenario-playbooks
Building or auditing a KB or memory system end to end?	Classify the workload first, then audit the seven responsibilities (admission to materialisation) one by one; when precision and coverage both matter, link current state to its evidence (P22)	memory-responsibilities-audit
Is a memory/retrieval service safe to adopt?	Keep app-owned truth, provenance, isolation, retention, and rebuild paths; compare engines by representation × output and the responsibilities they implement natively	managed-memory boundaries, security threat model, vendor landscape

Use This Skill When

• deciding between tools, SQL, RAG, vector search, graph, or memory for an app surface
• designing or reviewing user, customer/org, domain, action, or multi-surface context
• defining context assembly, typed contracts, freshness, ACL scope, provenance, or token budgets
• designing multimodal context or org-scale context systems, and deciding when to clear or compact context mid-session
• assessing a managed memory/retrieval product without surrendering app-owned truth

Do Not Use This Skill For

• repo-local instruction systems such as AGENTS.md, CLAUDE.md, or .claude/rules/
• pure code graphs, blast-radius analysis, or multi-repo inventory
• retrieval-only tuning when the broader context architecture is already decided
• prompt shape, structured output, or few-shot authoring

Route elsewhere: retrieval, grounding, citation corpora, and retrieve-vs-preload choices -> ai-rag; pgvector schemas and index builds -> ai-vector-brain; fine-tuning -> ai-llm. Use ai-agents for agent tools/approvals/rollouts, ai-prompt-engineering for prompt shape, software-ai-integration for shipping a feature, and the dev-context-* skills for repo context and graphs.

Core Workflow

1. Classify the request. Choose profile/personalization, memory, retrieval/grounding, relationship context, assembly, multimodal, knowledge-base ingestion, or review/build. Route pure retrieval, repo context, and agent-control work to its owner. When the scenario is known, load memory-scenario-playbooks first and take its stage defaults; otherwise classify the workload with memory-responsibilities-audit.
2. Choose the source of truth. Keep operational facts in authoritative tools or stores. Separate derived memory, raw episodes, retrieved evidence, and user-supplied context; attach provenance, owner scope, freshness, and retention requirements.
3. Select the smallest pattern. Use the decision matrix in patterns-catalog, then load only the matching reference architecture or layer deep dive. Do not preload the full stance, vendor landscape, or recipe catalog.
4. Define contracts and lifecycle. Specify typed projections for EntityProfile, LearnedMemory, KnowledgeSource, RetrievalResult, ContextAssemblyRequest, ContextBundle, feedback, and artifact references. Define write, select, compress, isolate, order, and format behavior for the consuming surface.
5. Apply admission and threat gates. Check authority, tenancy/ACL, freshness, provenance, token budget, contradiction handling, prompt-injection/poisoning risk, and deletion or rebuild paths. Keep tool permissions and human approvals in the consuming runtime; this skill does not grant them.
6. Validate the proposed boundary. Test retrieval/assembly quality, isolation, freshness, contradiction and erasure paths, context hygiene, and model/provider portability at the relevant evidence level. For staged memory mutations, run the SQLite lifecycle reference on disk; then test the selected engine with its actual role and configuration. Report skipped engine suites as untested. For claims that these skills improve an agent, use the paired skills ablation with an independent holdout.
7. Report completion. State the architecture decision, contracts, assumptions, evidence, checks, unresolved unknowns, and next bounded step. Continue through implementation, inspection, and fixes until the requested local outcome is complete or a named external/runtime gate remains.

Context Admission Gate

For every candidate item, attach the available envelope metadata: source class (operational, retrieved, derived, or user-supplied), owner scope, observed or effective time, provenance ID, and token cost. For a direct user turn, default provenance to the session and turn ID and time to receipt; do not require the user to supply system metadata. Admit an item only when the requesting surface is authorized, freshness is adequate, and it fits the surface budget after higher-authority items. Exclude it for missing metadata only when that missing field is material to authority, isolation, or freshness. Record the item ID, class, and exclusion reason; do not retain rejected raw content unless retention is explicitly authorized.

Context Mutation

Clearing or compacting context mid-session forces the provider cache to rewrite everything after the edit point. Clear only when cleared_tokens × read_price × remaining_turns > rewritten_suffix_tokens × (write_price − read_price); otherwise keep the tokens and mutate at the next task boundary. Before any compaction, pin a must-survive set and fail the compaction if a recall probe loses any pinned item. Worked example and probe: context-hygiene. Prefix layout itself belongs to ai-prompt-engineering.

Safety and Portability

• Keep model/provider choices behind vendor-neutral contracts and adapters. Re-verify context limits, cache behavior, managed-memory capabilities, and version-specific claims for the consuming model.
• Never treat raw chat, tool payloads, embeddings, or retrieved documents as trusted durable memory. Extract typed facts, preserve source episodes, and keep a correction, invalidation, erasure, and rebuild path.
• Treat tenant isolation, ACL scope, provenance, freshness, and prompt-injection defenses as runtime controls that must be tested at the relevant boundary. A prose review or local fixture does not prove production isolation; apply scope at candidate generation and run the cross-tenant canary test on every assembly, cache-key or filter change.
• Keep irreversible writes, external actions, and human approvals in the consuming runtime’s explicit policy. Existing authorization for the requested local work remains valid; do not repeat it unnecessarily.

Completion Contract

A design review is complete when the selected pattern, source boundaries, typed contracts, admission rules, validation checks, evidence level, and unresolved assumptions are recorded. A build task is complete only after the changed artifact is inspected, relevant checks pass, failures are fixed, and runtime or external gates are clearly identified. Distinguish static bundle validation, local fixture evidence, runtime loading, observed routing, and production behavior.

Navigation

• Scope and detailed route examples: context-scope
• Stance, context-window failure modes, and runtime verbs: stance-and-hygiene
• Architecture flow, build kit, templates, and admission detail: architecture-and-build
• Full reference map, scripts, data, fact-checking, and operations: context-navigation
• Architecture model and review workflow: context-layer-detail
• Scenario playbooks: memory-scenario-playbooks
• Stack crosswalk (storage, maintenance, engine mechanisms, query modes): memory-stack-crosswalk
• Pattern selection: patterns-catalog (P4 holds the bitemporal vocabulary), reference-architectures, architectures-by-organization, substrate-combinations
• Retrieval and grounding: retrieval-and-grounding, ai-rag, just-in-time-context-loading, retrieve-vs-preload-vs-finetune
• Memory and assembly: entity-and-memory-models, context-assembly, semantic-caching, managed-memory-boundaries, multimodal-context-assembly
• Hygiene, threats, and evaluation: context-hygiene, security-threat-model, evals-and-operations (state-maintenance eval), context-layer-scorecard
• Ingestion and organisation-scale patterns: git-anchored-ingestion, policy-and-compliance-docs, company-brain-assembly, composition-with-related-skills
• Persistent lifecycle implementation and adversarial cases: sqlite-memory-lifecycle
• Architecture alternatives: architecture-patterns, long-context-first-architecture, cache-augmented-generation, filesystem-as-memory, operational-brain-pattern, fine-tune-for-behavior-not-facts
• Wiki and chunking (P7): knowledge-compilation-and-wiki-pattern, multi-source-wiki-ingestion, markdown-chunking-patterns
• Delivery surfaces: mcp-context-delivery, conversational-surfaces-cross-platform, inspection-and-review-surfaces
• Review aids: anti-patterns-catalog, example-assessments, agent-memory-benchmarks, information-theory-applied
• Build-grade work: builds/README, builds/TUTORIAL
• Contracts and templates: design templates, review template, contract templates, entity and memory contract, feedback outcome contract
• Scripts and data: score_context_layer.py, check_sources.py, sources.json

Learnings Loop

Consult relevant entries in learnings.consolidated.md when prior context-layer decisions or known pitfalls matter; otherwise skip it. Read raw learnings.md history only when a repeated failure, provenance question, or unresolved decision needs it. After applying the skill, record a dated learning only when an observed pattern or mistake is worth preserving, using agents-skills-feedback-loop/scripts/append_learning.py; do not modify this file.