@bastani/atomic 0.7.17 → 0.8.0-0

package/dist/builtin/workflows/skills/workflow/references/context-engineering/hosted-agents.md

@@ -0,0 +1,262 @@
+---
+name: hosted-agents
+description: This skill should be used when the user asks to "build background agent", "create hosted coding agent", "set up sandboxed execution", "implement multiplayer agent", or mentions background agents, sandboxed VMs, agent infrastructure, Modal sandboxes, self-spawning agents, or remote coding environments. Part of the context engineering skill suite — also activates when the user mentions "context engineering" or "context-engineering" in the context of agent deployment and execution infrastructure.
+metadata:
+  provider: atomic
+---
+
+# Hosted Agent Infrastructure
+
+Hosted agents run in remote sandboxed environments rather than on local machines. When designed well, they provide unlimited concurrency, consistent execution environments, and multiplayer collaboration. The critical insight is that session speed should be limited only by model provider time-to-first-token, with all infrastructure setup completed before the user starts their session.
+
+## When to Activate
+
+Activate this skill when:
+- Building background coding agents that run independently of user devices
+- Designing sandboxed execution environments for agent workloads
+- Implementing multiplayer agent sessions with shared state
+- Creating multi-client agent interfaces (Slack, Web, Chrome extensions)
+- Scaling agent infrastructure beyond local machine constraints
+- Building systems where agents spawn sub-agents for parallel work
+
+## Core Concepts
+
+Move agent execution to remote sandboxed environments to eliminate the fundamental limits of local execution: resource contention, environment inconsistency, and single-user constraints. Remote sandboxes unlock unlimited concurrency, reproducible environments, and collaborative workflows because each session gets its own isolated compute with a known-good environment image.
+
+Design the architecture in three layers because each layer scales independently. Build sandbox infrastructure for isolated execution, an API layer for state management and client coordination, and client interfaces for user interaction across platforms. Keep these layers cleanly separated so sandbox changes do not ripple into clients.
+
+## Detailed Topics
+
+### Sandbox Infrastructure
+
+**The Core Challenge**
+Eliminate sandbox spin-up latency because users perceive anything over a few seconds as broken. Development environments require cloning repositories, installing dependencies, and running build steps -- do all of this before the user ever submits a prompt.
+
+**Image Registry Pattern**
+Pre-build environment images on a regular cadence (every 30 minutes works well) because this makes synchronization with the latest code a fast delta rather than a full clone. Include in each image:
+- Cloned repository at a known commit
+- All runtime dependencies installed
+- Initial setup and build commands completed
+- Cached files from running app and test suite once
+
+When starting a session, spin up a sandbox from the most recent image. The repository is at most 30 minutes out of date, making the remaining git sync fast.
+
+**Snapshot and Restore**
+Take filesystem snapshots at key points to enable instant restoration for follow-up prompts without re-running setup:
+- After initial image build (base snapshot)
+- When agent finishes making changes (session snapshot)
+- Before sandbox exit for potential follow-up
+
+**Git Configuration for Background Agents**
+Configure git identity explicitly in every sandbox because background agents are not tied to a specific user during image builds:
+- Generate GitHub app installation tokens for repository access during clone
+- Set git config `user.name` and `user.email` when committing and pushing changes
+- Use the prompting user's identity for commits, not the app identity
+
+**Warm Pool Strategy**
+Maintain a pool of pre-warmed sandboxes for high-volume repositories because cold starts are the primary source of user frustration:
+- Keep sandboxes ready before users start sessions
+- Expire and recreate pool entries as new image builds complete
+- Start warming a sandbox as soon as a user begins typing (predictive warm-up)
+
+### Agent Framework Selection
+
+**Server-First Architecture**
+Structure the agent framework as a server first, with TUI and desktop apps as thin clients, because this prevents duplicating agent logic across surfaces:
+- Multiple custom clients share one agent backend
+- Consistent behavior across all interaction surfaces
+- Plugin systems extend functionality without client changes
+- Event-driven architectures deliver real-time updates to any connected client
+
+**Code as Source of Truth**
+Select frameworks where the agent can read its own source code to understand behavior. Prioritize this because having code as source of truth prevents the agent from hallucinating about its own capabilities -- an underrated failure mode in AI development.
+
+**Plugin System Requirements**
+Require a plugin system that supports runtime interception because this enables safety controls and observability without modifying core agent logic:
+- Listen to tool execution events (e.g., `tool.execute.before`)
+- Block or modify tool calls conditionally
+- Inject context or state at runtime
+
+### Speed Optimizations
+
+**Predictive Warm-Up**
+Start warming the sandbox as soon as a user begins typing their prompt, not when they submit it, because the typing interval (5-30 seconds) is enough to complete most setup:
+- Clone latest changes in parallel with user typing
+- Run initial setup before user hits enter
+- For fast spin-up, sandbox can be ready before user finishes typing
+
+**Parallel File Reading**
+Allow the agent to start reading files immediately even if sync from latest base branch is not complete, because in large repositories incoming prompts rarely touch recently-changed files:
+- Agent can research immediately without waiting for git sync
+- Block file edits (not reads) until synchronization completes
+- This separation is safe because read-time data staleness of 30 minutes rarely matters for research
+
+**Maximize Build-Time Work**
+Move everything possible to the image build step because build-time duration is invisible to users:
+- Full dependency installation
+- Database schema setup
+- Initial app and test suite runs (populates caches)
+
+### Self-Spawning Agents
+
+**Agent-Spawned Sessions**
+Build tools that allow agents to spawn new sessions because frontier models are capable of decomposing work and coordinating sub-tasks:
+- Research tasks across different repositories
+- Parallel subtask execution for large changes
+- Multiple smaller PRs from one major task
+
+Expose three primitives: start a new session with specified parameters, read status of any session (check-in capability), and continue main work while sub-sessions run in parallel.
+
+**Prompt Engineering for Self-Spawning**
+Engineer prompts that guide when agents should spawn sub-sessions rather than doing work inline:
+- Research tasks that require cross-repository exploration
+- Breaking monolithic changes into smaller PRs
+- Parallel exploration of different approaches
+
+### API Layer
+
+**Per-Session State Isolation**
+Isolate state per session (SQLite per session works well) because cross-session interference is a subtle and hard-to-debug failure mode:
+- Dedicated database per session
+- No session can impact another's performance
+- Architecture handles hundreds of concurrent sessions
+
+**Real-Time Streaming**
+Stream all agent work in real-time because high-frequency feedback is critical for user trust:
+- Token streaming from model providers
+- Tool execution status updates
+- File change notifications
+
+Use WebSocket connections with hibernation APIs to reduce compute costs during idle periods while maintaining open connections.
+
+**Synchronization Across Clients**
+Build a single state system that synchronizes across all clients (chat interfaces, Slack bots, Chrome extensions, web interfaces, VS Code instances) because users switch surfaces frequently and expect continuity. All changes sync to the session state, enabling seamless client switching.
+
+### Multiplayer Support
+
+**Why Multiplayer Matters**
+Design for multiplayer from day one because it is nearly free to add with proper synchronization architecture, and it unlocks high-value workflows:
+- Teaching non-engineers to use AI effectively
+- Live QA sessions with multiple team members
+- Real-time PR review with immediate changes
+- Collaborative debugging sessions
+
+**Implementation Requirements**
+Build the data model so sessions are not tied to single authors because multiplayer fails silently if authorship is hardcoded:
+- Pass authorship info to each prompt
+- Attribute code changes to the prompting user
+- Share session links for instant collaboration
+
+### Authentication and Authorization
+
+**User-Based Commits**
+Use GitHub authentication to open PRs on behalf of the user (not the app) because this preserves the audit trail and prevents users from approving their own AI-generated changes:
+- Obtain user tokens for PR creation
+- PRs appear as authored by the human, not the bot
+
+**Sandbox-to-API Flow**
+Follow this sequence because it keeps sandbox permissions minimal while letting the API handle sensitive operations:
+1. Sandbox pushes changes (updating git user config)
+2. Sandbox sends event to API with branch name and session ID
+3. API uses user's GitHub token to create PR
+4. GitHub webhooks notify API of PR events
+
+### Client Implementations
+
+**Slack Integration**
+Prioritize Slack as the first distribution channel for internal adoption because it creates a virality loop as team members see others using it:
+- No syntax required, natural chat interface
+- Build a classifier (fast model with repo descriptions) to determine which repository to work in
+- Include hints for common repositories; allow "unknown" for ambiguous cases
+
+**Web Interface**
+Build a web interface with these features because it serves as the primary power-user surface:
+- Real-time streaming of agent work on desktop and mobile
+- Hosted VS Code instance running inside sandbox
+- Streamed desktop view for visual verification
+- Before/after screenshots for PRs
+- Statistics page: sessions resulting in merged PRs (primary metric), usage over time, live "humans prompting" count
+
+**Chrome Extension**
+Build a Chrome extension for non-engineering users because DOM and React internals extraction gives higher precision than raw screenshots at lower token cost:
+- Sidebar chat interface with screenshot tool
+- Extract DOM/React internals instead of raw images
+- Distribute via managed device policy (bypasses Chrome Web Store)
+
+## Practical Guidance
+
+### Follow-Up Message Handling
+
+Choose between queueing and inserting follow-up messages sent during execution. Prefer queueing because it is simpler to manage and lets users send thoughts on next steps while the agent works. Build a mechanism to stop the agent mid-execution when needed, because without it users feel trapped.
+
+### Metrics That Matter
+
+Track these metrics because they indicate real value rather than vanity usage:
+- Sessions resulting in merged PRs (primary success metric)
+- Time from session start to first model response
+- PR approval rate and revision count
+- Agent-written code percentage across repositories
+
+### Adoption Strategy
+
+Drive internal adoption through visibility rather than mandates because forced usage breeds resentment:
+- Work in public spaces (Slack channels) for visibility
+- Let the product create virality loops
+- Do not force usage over existing tools
+- Build to people's needs, not hypothetical requirements
+
+## Guidelines
+
+1. Pre-build environment images on regular cadence (30 minutes is a good default)
+2. Start warming sandboxes when users begin typing, not when they submit
+3. Allow file reads before git sync completes; block only writes
+4. Structure agent framework as server-first with clients as thin wrappers
+5. Isolate state per session to prevent cross-session interference
+6. Attribute commits to the user who prompted, not the app
+7. Track merged PRs as primary success metric
+8. Build for multiplayer from the start; it is nearly free with proper sync architecture
+
+## Gotchas
+
+1. **Cold start latency**: First sandbox spin-up takes 30-60s and users perceive this as broken. Use warm pools and predictive warm-up on keystroke to eliminate perceived wait time.
+2. **Image staleness**: Infrequent image rebuilds mean agents run with outdated dependencies or code. Set a 30-minute rebuild cadence and monitor image age; alert if builds fail silently.
+3. **Sandbox cost runaway**: Long-running agents without timeout or budget caps accumulate unexpected costs. Set hard timeout limits (default 4 hours) and per-session cost ceilings.
+4. **Auth token expiration mid-session**: Long tasks fail when GitHub tokens expire partway through. Implement token refresh logic and check token validity before sensitive operations like PR creation.
+5. **Git config in sandboxes**: Missing `user.name` or `user.email` causes commit failures in background agents. Always set git identity explicitly during sandbox configuration, never assume it carries over from the image.
+6. **State loss on sandbox recycle**: Agents lose completed work if the sandbox is recycled or times out before results are extracted. Always snapshot before termination and extract artifacts (branches, PRs, files) before letting the sandbox die.
+7. **Oversubscribing warm pools**: Maintaining too many warm sandboxes wastes money during low-traffic periods. Scale pool size based on traffic patterns and time-of-day; use autoscaling rather than fixed pool sizes.
+8. **Missing output extraction**: Agents complete work inside the sandbox but results never get pulled out to the user. Build explicit extraction steps (push branch, create PR, return file contents) into the session teardown flow.
+
+## Integration
+
+This skill builds on multi-agent-patterns for agent coordination and tool-design for agent-tool interfaces. It connects to:
+
+- multi-agent-patterns - Self-spawning agents follow supervisor patterns
+- tool-design - Building tools for agent spawning and status checking
+- context-optimization - Managing context across distributed sessions
+- filesystem-context - Using filesystem for session state and artifacts
+
+## References
+
+Internal reference:
+- [Infrastructure Patterns](./references/infrastructure-patterns.md) - Read when: implementing sandbox lifecycle, image builds, or warm pool logic for the first time
+
+Related skills in this collection:
+- multi-agent-patterns - Read when: designing self-spawning or supervisor coordination patterns
+- tool-design - Read when: building tools for agent session management or status checking
+- context-optimization - Read when: context windows fill up across distributed agent sessions
+
+External resources:
+- [Ramp](https://builders.ramp.com/post/why-we-built-our-background-agent) - Read when: evaluating whether to build vs. buy background agent infrastructure
+- [Modal Sandboxes](https://modal.com/docs/guide/sandbox) - Read when: choosing a cloud sandbox provider or comparing isolation models
+- [Cloudflare Durable Objects](https://developers.cloudflare.com/durable-objects/) - Read when: designing per-session state management with WebSocket hibernation
+- [OpenCode](https://github.com/sst/opencode) - Read when: selecting a server-first agent framework or studying plugin architectures
+
+---
+
+## Skill Metadata
+
+**Created**: 2026-01-12
+**Last Updated**: 2026-03-17
+**Author**: Agent Skills for Context Engineering Contributors
+**Version**: 1.1.0

package/dist/builtin/workflows/skills/workflow/references/context-engineering/memory-systems.md

@@ -0,0 +1,221 @@
+---
+name: memory-systems
+description: Guides implementation of agent memory systems, compares production frameworks (Mem0, Zep/Graphiti, Letta, LangMem, Cognee), and designs persistence architectures for cross-session knowledge retention. Use when the user asks to "implement agent memory", "persist state across sessions", "build knowledge graph for agents", "track entities over time", "add long-term memory", "choose a memory framework", or mentions temporal knowledge graphs, vector stores, entity memory, adaptive memory, dynamic memory, or memory benchmarks (LoCoMo, LongMemEval). A core context engineering skill — also activates when the user mentions "context engineering" or "context-engineering" in the context of durable agent knowledge and cross-session persistence.
+metadata:
+  provider: atomic
+---
+
+# Memory System Design
+
+Memory provides the persistence layer that allows agents to maintain continuity across sessions and reason over accumulated knowledge. Simple agents rely entirely on context for memory, losing all state when sessions end. Sophisticated agents implement layered memory architectures that balance immediate context needs with long-term knowledge retention. The evolution from vector stores to knowledge graphs to temporal knowledge graphs represents increasing investment in structured memory for improved retrieval and reasoning.
+
+## When to Activate
+
+Activate this skill when:
+- Building agents that must persist knowledge across sessions
+- Choosing between memory frameworks (Mem0, Zep/Graphiti, Letta, LangMem, Cognee)
+- Needing to maintain entity consistency across conversations
+- Implementing reasoning over accumulated knowledge
+- Designing memory architectures that scale in production
+- Evaluating memory systems against benchmarks (LoCoMo, LongMemEval, DMR)
+- Building dynamic memory with automatic entity/relationship extraction and self-improving memory (Cognee)
+
+## Core Concepts
+
+Think of memory as a spectrum from volatile context window to persistent storage. Default to the simplest layer that meets retrieval needs, because benchmark evidence shows **tool complexity matters less than reliable retrieval** — Letta's filesystem agents scored 74% on LoCoMo using basic file operations, beating Mem0's specialized tools at 68.5%. Add structure (graphs, temporal validity) only when retrieval quality degrades or the agent needs multi-hop reasoning, relationship traversal, or time-travel queries.
+
+## Detailed Topics
+
+### Production Framework Landscape
+
+Select a framework based on the dominant retrieval pattern the agent requires. Use this table to narrow the shortlist, then validate with the benchmark data below.
+
+| Framework | Architecture | Best For | Trade-off |
+|-----------|-------------|----------|-----------|
+| **Mem0** | Vector store + graph memory, pluggable backends | Multi-tenant systems, broad integrations | Less specialized for multi-agent |
+| **Zep/Graphiti** | Temporal knowledge graph, bi-temporal model | Enterprise requiring relationship modeling + temporal reasoning | Advanced features cloud-locked |
+| **Letta** | Self-editing memory with tiered storage (in-context/core/archival) | Full agent introspection, stateful services | Complexity for simple use cases |
+| **Cognee** | Multi-layer semantic graph via customizable ECL pipeline with customizable Tasks | Evolving agent memory that adapts and learns; multi-hop reasoning | Heavier ingest-time processing |
+| **LangMem** | Memory tools for LangGraph workflows | Teams already on LangGraph | Tightly coupled to LangGraph |
+| **File-system** | Plain files with naming conventions | Simple agents, prototyping | No semantic search, no relationships |
+
+Choose Zep/Graphiti when the agent needs bi-temporal modeling (tracking both when events occurred and when they were ingested) because its three-tier knowledge graph (episode, semantic entity, community subgraphs) excels at temporal queries. Choose Mem0 when the priority is fast time-to-production with managed infrastructure. Choose Letta when the agent needs deep self-introspection through its Agent Development Environment. Choose Cognee when the agent must build dense multi-layer semantic graphs — it layers text chunks and entity types as nodes with detailed relationship edges, and every core piece (ingestion, entity extraction, post-processing, retrieval) is customizable.
+
+**Benchmark Performance Comparison**
+
+Consult these benchmarks to set expectations, but treat them as signals for specific retrieval dimensions rather than absolute rankings. No single benchmark is definitive.
+
+| System | DMR Accuracy | LoCoMo | HotPotQA (multi-hop) | Latency |
+|--------|-------------|--------|---------------------|---------|
+| Cognee | — | — | Highest on EM, F1, Correctness | Variable |
+| Zep (Temporal KG) | 94.8% | — | Mid-range across metrics | 2.58s |
+| Letta (filesystem) | — | 74.0% | — | — |
+| Mem0 | — | 68.5% | Lowest across metrics | — |
+| MemGPT | 93.4% | — | — | Variable |
+| GraphRAG | ~75-85% | — | — | Variable |
+| Vector RAG baseline | ~60-70% | — | — | Fast |
+
+Key takeaways: Zep achieves up to 18.5% accuracy improvement on LongMemEval while reducing latency by 90%. Cognee outperformed Mem0, Graphiti, and LightRAG on HotPotQA multi-hop reasoning benchmarks across Exact Match, F1, and human-like correctness metrics. Letta's filesystem-based agents achieved 74% on LoCoMo using basic file operations, confirming that reliable retrieval beats tool sophistication.
+
+### Memory Layers (Decision Points)
+
+Pick the shallowest memory layer that satisfies the persistence requirement. Each deeper layer adds infrastructure cost and operational complexity, so only escalate when the shallower layer cannot meet the retrieval or durability need.
+
+| Layer | Persistence | Implementation | When to Use |
+|-------|------------|----------------|-------------|
+| **Working** | Context window only | Scratchpad in system prompt | Always — optimize with attention-favored positions |
+| **Short-term** | Session-scoped | File-system, in-memory cache | Intermediate tool results, conversation state |
+| **Long-term** | Cross-session | Key-value store → graph DB | User preferences, domain knowledge, entity registries |
+| **Entity** | Cross-session | Entity registry + properties | Maintaining identity ("John Doe" = same person across conversations) |
+| **Temporal KG** | Cross-session + history | Graph with validity intervals | Facts that change over time, time-travel queries, preventing context clash |
+
+### Retrieval Strategies
+
+Match the retrieval strategy to the query shape. Semantic search handles direct factual lookups well but degrades on multi-hop reasoning; entity-based traversal handles "everything about X" queries but requires graph structure; temporal filtering handles changing facts but requires validity metadata. When accuracy is paramount and infrastructure budget allows, combine strategies into hybrid retrieval.
+
+| Strategy | Use When | Limitation |
+|----------|----------|------------|
+| **Semantic** (embedding similarity) | Direct factual queries | Degrades on multi-hop reasoning |
+| **Entity-based** (graph traversal) | "Tell me everything about X" | Requires graph structure |
+| **Temporal** (validity filter) | Facts change over time | Requires validity metadata |
+| **Hybrid** (semantic + keyword + graph) | Best overall accuracy | Most infrastructure |
+
+Zep's hybrid approach achieves 90% latency reduction (2.58s vs 28.9s) by retrieving only relevant subgraphs. Cognee implements hybrid retrieval through its 14 search modes — each mode combines different strategies from its three-store architecture (graph, vector, relational), letting agents select the retrieval strategy that fits the query type rather than using a one-size-fits-all approach.
+
+### Memory Consolidation
+
+Run consolidation periodically to prevent unbounded growth, because unchecked memory accumulation degrades retrieval quality over time. **Invalidate but do not discard** — preserving history matters for temporal queries that need to reconstruct past states. Trigger consolidation on memory count thresholds, degraded retrieval quality, or scheduled intervals. See [Implementation Reference](./references/implementation.md) for working consolidation code.
+
+## Practical Guidance
+
+### Choosing a Memory Architecture
+
+**Start with the simplest viable layer and add complexity only when retrieval quality degrades.** Most agents do not need a temporal knowledge graph on day one. Follow this escalation path:
+
+1. **Prototype**: Use file-system memory. Store facts as structured JSON with timestamps. This validates agent behavior before committing to infrastructure.
+2. **Scale**: Move to Mem0 or a vector store with metadata when the agent needs semantic search and multi-tenant isolation, because file-based lookup cannot handle similarity queries.
+3. **Complex reasoning**: Add Zep/Graphiti when the agent needs relationship traversal, temporal validity, or cross-session synthesis. Graphiti uses structured ties with generic relations, keeping graphs simple and easy to reason about; Cognee builds denser multi-layer semantic graphs with detailed relationship edges — choose based on whether the agent needs temporal bi-modeling (Graphiti) or richer interconnected knowledge structures (Cognee).
+4. **Full control**: Use Letta or Cognee when the agent must self-manage its own memory with deep introspection, because these frameworks expose memory operations as first-class agent actions.
+
+### Integration with Context
+
+Load memories just-in-time rather than preloading everything, because large context payloads are expensive and degrade attention quality. Place retrieved memories in attention-favored positions (beginning or end of context) to maximize their influence on generation.
+
+### Error Recovery
+
+Handle retrieval failures gracefully because memory systems are inherently noisy. Apply these recovery strategies in order:
+
+- **Empty retrieval**: Fall back to broader search (remove entity filter, widen time range). If still empty, prompt user for clarification.
+- **Stale results**: Check `valid_until` timestamps. If most results are expired, trigger consolidation before retrying.
+- **Conflicting facts**: Prefer the fact with the most recent `valid_from`. Surface the conflict to the user if confidence is low.
+- **Storage failure**: Queue writes for retry. Never block the agent's response on a memory write.
+
+## Examples
+
+**Example 1: Mem0 Integration**
+```python
+from mem0 import Memory
+
+m = Memory()
+m.add("User prefers dark mode and Python 3.12", user_id="alice")
+m.add("User switched to light mode", user_id="alice")
+
+# Retrieves current preference (light mode), not outdated one
+results = m.search("What theme does the user prefer?", user_id="alice")
+```
+
+**Example 2: Temporal Query**
+```python
+# Track entity with validity periods
+graph.create_temporal_relationship(
+    source_id=user_node,
+    rel_type="LIVES_AT",
+    target_id=address_node,
+    valid_from=datetime(2024, 1, 15),
+    valid_until=datetime(2024, 9, 1),  # moved out
+)
+
+# Query: Where did user live on March 1, 2024?
+results = graph.query_at_time(
+    {"type": "LIVES_AT", "source_label": "User"},
+    query_time=datetime(2024, 3, 1)
+)
+```
+
+**Example 3: Cognee Memory Ingestion and Search**
+```python
+import cognee
+from cognee.modules.search.types import SearchType
+
+# Ingest and build knowledge graph
+await cognee.add("./docs/")
+await cognee.add("any data")
+await cognee.cognify()
+
+# Enrich memory
+await cognee.memify()
+
+# Agent retrieves relationship-aware context
+results = await cognee.search(
+    query_text="Any query for your memory",
+    query_type=SearchType.GRAPH_COMPLETION,
+)
+```
+
+## Guidelines
+
+1. Start with file-system memory; add complexity only when retrieval quality demands it
+2. Track temporal validity for any fact that can change over time
+3. Use hybrid retrieval (semantic + keyword + graph) for best accuracy
+4. Consolidate memories periodically — invalidate but don't discard
+5. Design for retrieval failure: always have a fallback when memory lookup returns nothing
+6. Consider privacy implications of persistent memory (retention policies, deletion rights)
+7. Benchmark your memory system against LoCoMo or LongMemEval before and after changes
+8. Monitor memory growth and retrieval latency in production
+
+## Gotchas
+
+1. **Stuffing everything into context**: Loading all available memories into the prompt is expensive and degrades attention quality. Use just-in-time retrieval with relevance filtering instead.
+2. **Ignoring temporal validity**: Facts go stale. Without validity tracking, outdated information poisons the context and the agent acts on wrong assumptions.
+3. **Over-engineering early**: A filesystem agent can outperform complex memory tooling (Letta scored 74% vs Mem0's 68.5% on LoCoMo). Add sophistication only when simple approaches demonstrably fail.
+4. **No consolidation strategy**: Unbounded memory growth degrades retrieval quality over time. Set memory count thresholds or scheduled intervals to trigger consolidation.
+5. **Embedding model mismatch**: Writing memories with one embedding model and reading with another produces poor retrieval because vector spaces are not interchangeable. Pin a single embedding model for each memory store and re-embed all entries if the model changes.
+6. **Graph schema rigidity**: Over-structured graph schemas (rigid node types, fixed relationship labels) break when the domain evolves. Prefer generic relation types and flexible property bags so new entity kinds do not require schema migrations.
+7. **Stale memory poisoning**: Old memories that contradict the current state corrupt agent behavior silently. Implement expiry policies or confidence decay so the agent deprioritizes aged facts, and surface contradictions explicitly when detected.
+8. **Memory-context mismatch**: Retrieving memories that are topically related but contextually wrong (e.g., a memory about "Python" the snake when the agent is discussing Python the language). Mitigate by including session or domain metadata in memory entries and filtering on it during retrieval.
+
+## Integration
+
+This skill builds on context-fundamentals. It connects to:
+
+- multi-agent-patterns - Shared memory across agents
+- context-optimization - Memory-based context loading
+- evaluation - Evaluating memory quality
+
+## References
+
+Internal references:
+- [Implementation Reference](./references/implementation.md) - Read when: implementing vector stores, property graphs, temporal queries, or memory consolidation logic from scratch
+
+Related skills in this collection:
+- context-fundamentals - Read when: designing the context layer that memory feeds into
+- multi-agent-patterns - Read when: multiple agents need to share or coordinate memory state
+
+External resources:
+- Zep temporal knowledge graph paper (arXiv:2501.13956) - Read when: evaluating bi-temporal modeling or Graphiti's architecture
+- Mem0 production architecture paper (arXiv:2504.19413) - Read when: assessing managed memory infrastructure trade-offs
+- Cognee optimized knowledge graph + LLM reasoning paper (arXiv:2505.24478) - Read when: comparing multi-layer semantic graph approaches
+- LoCoMo benchmark (Snap Research) - Read when: evaluating long-conversation memory retention
+- MemBench evaluation framework (ACL 2025) - Read when: designing memory evaluation suites
+- Graphiti open-source temporal KG engine (github.com/getzep/graphiti) - Read when: implementing temporal knowledge graphs
+- Cognee open-source knowledge graph memory (github.com/topoteretes/cognee) - Read when: building customizable ECL pipelines for memory
+- [Cognee comparison: Form vs Function](https://www.cognee.ai/blog/deep-dives/competition-comparison-form-vs-function) - Read when: comparing graph structures across Mem0, Graphiti, LightRAG, Cognee
+
+---
+
+## Skill Metadata
+
+**Created**: 2025-12-20
+**Last Updated**: 2026-03-17
+**Author**: Agent Skills for Context Engineering Contributors
+**Version**: 4.0.0