AgentX: Skill for Claude Code

Cognitive Architecture

Purpose: Patterns for the cognitive components of AI agents: Memory, Knowledge (RAG), and Reasoning.

---

When to Use This Skill

• Designing Memory Systems (Conversation history, User profiles, Entity tracking).
• Building RAG Pipelines (Chunking, Embedding, Retrieval, Reranking).
• Managing Agent State across sessions.
• Selecting Vector Databases for knowledge retrieval.

Decision Tree

Designing agent cognition?
+-- Need conversation history? -> Short-term memory (context window)
+-- Need factual knowledge? -> RAG pipeline (vector store + retrieval)
+-- Need user preferences across sessions? -> Long-term memory (database-backed)
+-- Need entity tracking? -> Episodic memory (structured state store)
+-- Need all of the above? -> Full cognitive architecture (all three layers)
+-- Unsure where to start? -> Start with RAG, add memory as needed

Table of Contents

1. Cognitive Components
2. Reference Patterns
3. Troubleshooting

---

Cognitive Components

A complete agent "brain" consists of three layers:

1. Context (Short-term Memory): The active context window (conversation history).
2. Knowledge (Long-term Memory/RAG): Static facts retrieved from vector stores or databases.
3. State (Episodic Memory): Structured data about the user or task progress persisted indefinitely.

---

Core Rules

1. Layer separation - Keep context, knowledge, and state as independent modules with clear interfaces
2. Context window budget - Allocate token budgets per cognitive layer and never exceed the model context limit
3. Retrieval before generation - Always retrieve relevant knowledge before generating a response
4. Grounded responses - Instruct the model to use only retrieved context and refuse when context is insufficient
5. Memory lifecycle - Define TTL and eviction policies for each memory layer (short-term expires, long-term persists)
6. Metadata on every chunk - Store source, timestamp, and relevance score with all knowledge chunks
7. Test each layer independently - Evaluate retrieval quality, memory recall, and state consistency separately