# Context engineering layer map for AI agents

Use this open working record to decide where information belongs in an AI agent system. It is designed for both human architecture reviews and agent-readable implementation plans.

Canonical guide: https://handover.sh/guides/shared-context-vs-agent-memory

Machine-readable record: https://handover.sh/examples/context-engineering-layer-map.json

## Direct answer

Context engineering is not one memory store. A production agent system usually needs five layers:

1. **Instructions** define the role, constraints, tools, and output contract.
2. **Working context** contains the immediate objective, recent observations, and relevant tool results.
3. **Runtime memory** recalls preferences or facts useful to the same application across sessions.
4. **Shared context** preserves attributable work that another person or agent must inspect and continue.
5. **Source artifacts** preserve the files, data, and evidence behind summaries and decisions.

Use the smallest layer that satisfies the task. Move information into shared context when work crosses an identity, model, tool, session, or organizational boundary.

## Layer map

| Layer | Use it for | Do not use it as | Typical lifetime | Required controls |
| --- | --- | --- | --- | --- |
| Instructions | Role, policy, tool rules, output contract | A history of task state | Run, agent, or policy version | Change control; clear precedence |
| Working context | Current objective, selected evidence, recent tool results | A permanent archive | Turn or active run | Relevance filtering; token budget |
| Runtime memory | User preferences, recurring facts, local continuity | The canonical team record | Sessions within one runtime | Consent; expiry; correction |
| Shared context | Decisions, status, ownership, review, next actions | Hidden reasoning or a secret store | Until retention policy expires | Identity; access; versions; attribution |
| Source artifacts | Markdown, SQL, HTML, code, images, data, reports | An unexplained file dump | Source retention period | Integrity; provenance; safe preview |

## Placement record

Complete one row for every durable information class. Keep the reason short enough for a future reviewer or agent to challenge.

| Information | Needed now? | Required actors | Evidence or audit need | Sensitivity | Chosen layer | Retention or expiry | Owner | Retrieval rule |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Current task objective | Yes | Active agent | Low | Internal | Working context | End of run | Task owner | Inject at run start |
| Approved architecture decision | Yes | Team and successor agents | High | Internal | Shared context | Project lifetime | Technical owner | Retrieve canonical revision |
| Customer formatting preference | Sometimes | Same user and runtime | Low | Personal | Runtime memory | Review after 90 days | User | Retrieve when relevant |
| Query used for a published result | On verification | Reviewers and successors | High | Restricted | Source artifact | Match report retention | Data owner | Attach to shared record |

## Decision rules

1. Keep it in **working context** when only the active run needs it.
2. Use **runtime memory** when the same application should recall it but no other actor needs a canonical record.
3. Use **shared context** when another authenticated actor must verify, review, update, or own the work.
4. Preserve a **source artifact** when a claim depends on an exact file, query, image, dataset, or report.
5. Use vector or hybrid retrieval to discover relevant material, not to decide authorship, approval, ownership, or the canonical revision.
6. Never store copied credentials, hidden reasoning, unrelated transcripts, or unnecessary personal data in a handoff.
7. Apply authorization before search and retrieval, not after a result has already been selected.

## Context placement record

Copy this block into an architecture decision or handoff.

```yaml
context_placement:
  information: ""
  immediate_task_relevance: required | useful | no
  required_actors: []
  durability: turn | run | session | project | policy
  evidence_requirement: none | traceable | reproducible
  sensitivity: public | internal | restricted
  chosen_layer: instructions | working_context | runtime_memory | shared_context | source_artifact
  owner: ""
  retention_or_expiry: ""
  retrieval_rule: ""
  reason: ""
```

## Implementation checklist

- [ ] Instructions have an explicit owner and precedence.
- [ ] Active context is selected for relevance instead of copied wholesale.
- [ ] Runtime memory has consent, correction, and expiry rules.
- [ ] Shared records have stable IDs, immutable revisions, and attributable authors.
- [ ] Source artifacts preserve their original type and integrity metadata.
- [ ] Search and retrieval enforce tenant and workspace access before returning results.
- [ ] Human annotations remain attached to the exact artifact and revision.
- [ ] Public visibility requires an explicit action by an authorized owner.
- [ ] Service agents use named, scoped, revocable identities.
- [ ] Retention and deletion apply to records, artifacts, indexes, and derived memory.

## Two-identity continuity test

Run this test with two separately authenticated actors and no shared chat.

1. Actor A publishes a uniquely marked objective, one decision, one source artifact, one open question, and the next action.
2. Actor A reads the record back and records its stable ID and current revision.
3. Actor B receives only the stable ID or unique search marker.
4. Actor B retrieves the exact revision, identifies the owner and next action, and reproduces one material fact from the artifact.
5. Actor B appends a new revision using the current revision ID.
6. A denied identity attempts the same retrieval and must receive no record or metadata.
7. Actor A attempts a write against the stale revision and must receive a conflict instead of overwriting Actor B.
8. Revoke Actor B's credential and confirm it can no longer read or write.

The workflow passes only when continuity succeeds for the authorized successor without weakening access control, attribution, or revision safety.

## Recommended publication boundary

Default durable context to private. A mention may notify an actor who already has access, but it must not grant access. Public context should have a separate publication surface that excludes private annotations, credentials, unrelated company material, and restricted source artifacts.

## Attribution

Published by the Handover product team at 44pixels. This checklist may be reused with attribution under CC BY 4.0.