Claude Agent: The Context Engineering Playbook

You finally ship a long session with an LLM, crack a design, and capture a dozen sharp insights. The next day it greets you like a goldfish. No history. No reasons. No momentum. The way out is simple to say and fun to build. Create a context aware AI that remembers what matters and improves as it works.

This guide shows how to use Claude agent capabilities to build real memory, real tools, and a clean loop for reliable output. We will use the Claude agent sdk, principles of context engineering, and a small set of patterns that scale. By the end, you will have a working research helper, a roadmap for long-term memory AI, and clear next steps to build an AI agent that earns its keep.

1. What Is A Claude Agent: The Agentic Loop

A Claude agent is a model that can use tools, reason over intermediate results, and run inside a loop. Think of a craftsman who can grab a saw, measure twice, and check the fit before moving on.
The loop has three beats.

• Gather Context. Load only the information needed now.
• Take Action. Call tools, write files, run code, or hit APIs.
• Verify Work. Check outputs against rules, summarize progress, and plan the next step.

That is the mental model. Design the context as carefully as the tools. Your Claude agent will only be as smart as what it sees and saves.

2. Context Engineering Vs Prompt Engineering: The Memory Key

Prompt engineering tunes the instruction. Context engineering that single shift unlocks reliable behavior.
Why it matters:

• Finite attention. Context is a budget. More tokens do not always mean better results.
• Context rot. As inputs grow, precision drops. Important details get buried.
• Signal beats noise. A crisp, minimal context outperforms an overloaded one.

A Claude agent improves when you curate what enters its window and when you persist state outside of it. That is where memory, structure, and tools show up.

3. Your Toolbox: Getting Started With The Claude Agent SDK

The Claude agent sdk gives you primitives that map to the loop.

• Tools. Declarative actions the model can call with parameters and returns.
• File System Access. Read and write notes, logs, and artifacts.
• Bash And Scripts. Run commands for search, parsing, and quick transforms.
• MCP Integrations. Connect to services like Slack, GitHub, or Drive with clean auth.
• Compaction. Summarize history when the context window gets tight.

Use the SDK to make the work legible. If a human would keep a notebook and a folder of references, your Claude agent should too.

4. Step 1, Gather Context: Agentic Search And A Memory Folder

Start with a folder that your agent treats as its second brain. Keep it boring and predictable.
Recommended layout

project/
  memory/
    NOTES.md
    decisions/
    research/
  tasks/
  outputs/

Goals

• Keep durable facts and decisions in memory/.
• Put transient results in outputs/.
• Name files so both humans and the agent can guess their purpose.

Minimal TypeScript helper

import { promises as fs } from "fs";
import path from "path";

const ROOT = process.env.PROJECT_ROOT || process.cwd();
const MEM = path.join(ROOT, "memory");

export async function ensureMemory() {
  await fs.mkdir(path.join(MEM, "decisions"), { recursive: true });
  await fs.mkdir(path.join(MEM, "research"), { recursive: true });
  const notes = path.join(MEM, "NOTES.md");
  try { await fs.access(notes); } catch { await fs.writeFile(notes, "# Notes\n"); }
}

export async function readNotes() {
  return fs.readFile(path.join(MEM, "NOTES.md"), "utf8");
}

export async function appendNote(markdown: string) {
  const file = path.join(MEM, "NOTES.md");
  await fs.appendFile(file, `

${new Date().toISOString()}
${markdown}
`);
}

export async function searchMemory(keyword: string) {
  const files = await fs.readdir(MEM, { withFileTypes: true });
  const hits: Array<{file: string; lines: string[]}> = [];
  for (const f of files) {
    if (!f.isFile()) continue;
    const text = await fs.readFile(path.join(MEM, f.name), "utf8");
    const lines = text.split("\n").filter(l => l.toLowerCase().includes(keyword.toLowerCase()));
    if (lines.length) hits.push({ file: f.name, lines });
  }
  return hits;
}

Give your Claude agent this directory and these helpers. It can now read its own notes, find prior work, and reuse evidence instead of guessing.

5. Step 2, Take Action: Tools And Sub-Agents

Teach your Claude agent to act in the world you define. Start with one essential tool, then add only what your use case truly needs.

A simple memory tool

import { appendNote } from "../helpers/memory";

export type SaveNoteArgs = { title: string; summary: string; tags?: string[] };

export async function save_note_to_memory(args: SaveNoteArgs) {
  const { title, summary, tags = [] } = args;
  const tagLine = tags.length ? `

Tags: ${tags.join(", ")}
` : "";
  await appendNote(`## ${title}
${summary}${tagLine}`);
  return { ok: true };
}

Registering the tool with the SDK

import { defineTool } from "claude-agent-sdk";
import { save_note_to_memory } from "./saveNote";

export const tools = [
  defineTool({
    name: "save_note_to_memory",
    description: "Persist a concise, structured note to memory/NOTES.md",
    inputSchema: {
      type: "object",
      properties: {
        title: { type: "string" },
        summary: { type: "string" },
        tags: { type: "array", items: { type: "string" } }
      },
      required: ["title", "summary"]
    },
    handler: save_note_to_memory
  })
];

Sub-agents are focused helpers with their own context windows. Use them to explore a codebase, triage documents, or scan logs. Each sub-agent returns a short, high-signal report to the orchestrator. Your Claude agent stays lean while the specialists dive deep.

6. Step 3, Verify Work: Structured Note-Taking Loop

Close the loop. Every interaction should end with a short, structured note written to durable memory. That single habit makes your Claude agent more consistent day after day.

Agent loop sketch

import { createAgent } from "claude-agent-sdk";
import { tools } from "./tools";
import { ensureMemory, readNotes } from "../helpers/memory";

export const agent = createAgent({
  name: "context-aware-helper",
  system: [
    "You are a pragmatic assistant.",
    "Always consult memory/NOTES.md before planning.",
    "After completing a task, summarize key decisions and facts.",
    "Prefer concise outputs and cite file paths you touched."
  ].join("\n"),
  tools
});

export async function runTask(userGoal: string) {
  await ensureMemory();
  const prior = await readNotes();

  const plan = await agent.run({
    messages: [
      { role: "user", content: `Goal: ${userGoal}` },
      { role: "assistant", content: `Relevant memory:
${prior.slice(-4000)}` }
    ]
  });

  // The plan should call save_note_to_memory as its final step.
  return plan;
}

This pattern keeps history compact, decisions explicit, and next steps obvious. Your Claude agent becomes predictable because it writes down what it did and why.

7. Putting It All Together: A Minimal Research Agent

Now build a tiny research helper that pulls a topic, skims sources, extracts signals, and saves a clean summary for tomorrow’s self.

import { createAgent, defineTool } from "claude-agent-sdk";
import { ensureMemory, appendNote } from "../helpers/memory";

/** Simple web fetcher for demonstration. Replace with your org's search tool. */
const fetch_pages = defineTool({
  name: "fetch_pages",
  description: "Fetch a list of URLs and return {url, title, text}",
  inputSchema: {
    type: "object",
    properties: { urls: { type: "array", items: { type: "string" } } },
    required: ["urls"]
  },
  handler: async ({ urls }: { urls: string[] }) => {
    const results: Array<{ url: string; title: string; text: string }> = [];
    for (const url of urls) {
      const res = await fetch(url);
      const html = await res.text();
      const title = (html.match(/<title>(.*?)<\/title>/i)?.[1] || url).trim();
      const text = html
        .replace(/<[^>]+>/g, " ")
        .replace(/\s+/g, " ")
        .slice(0, 30000);
      results.push({ url, title, text });
    }
    return { results };
  }
});

const save_summary = defineTool({
  name: "save_research_summary",
  description: "Save a concise research summary into memory/NOTES.md",
  inputSchema: {
    type: "object",
    properties: { topic: { type: "string" }, summary: { type: "string" } },
    required: ["topic", "summary"]
  },
  handler: async ({ topic, summary }: { topic: string; summary: string }) => {
    await appendNote(`## Research: ${topic}
${summary}`);
    return { ok: true };
  }
});

export const researchAgent = createAgent({
  name: "researcher",
  system: [
    "You are a careful researcher.",
    "When given a topic, propose 3-5 credible URLs.",
    "Use fetch_pages to read them, extract key claims with sources, and write a 10-bullet summary.",
    "Call save_research_summary with the final summary."
  ].join("\n"),
  tools: [fetch_pages, save_summary]
});

export async function research(topic: string) {
  await ensureMemory();
  return researchAgent.run({
    messages: [{ role: "user", content: `Topic: ${topic}` }]
  });
}

Run the Claude agent on a topic, inspect memory/NOTES.md, and notice how much easier your next session becomes. This is how to use Claude agent patterns to turn scattered effort into long-term memory AI.

8. Advanced Techniques: Compaction And Hybrid Retrieval

As projects grow, you need more than folders and notes.

8.1 Compaction

Compaction summarizes older turns to preserve intent, decisions, and open threads. Keep raw tool outputs out of history. Keep short, precise summaries in.

• Summarize conversation segments into bullet points with timestamps.
• Preserve design choices, file paths, and constraints.
• Keep the last few raw traces nearby when precision matters.

Compaction lets a Claude agent keep its edge as the work spans hours.

8.2 Hybrid Retrieval

Pair agentic file search with a vector index. Use a fast key value store for embeddings. Examples include Redis, SQLite extensions, or a hosted vector service.

• Use embeddings for quick recall of similar content.
• Use file system search for exact names, logs, and structured notes.
• Let the agent cite the source path every time.

Hybrid retrieval helps the Claude agent find the right sentence fast without flooding the window.

8.3 Sub-Agent Topologies

Give sub-agents a charter and a budget.

• Reader. Pulls context from files and returns a 400-word abstract with links.
• Planner. Converts goals into steps with acceptance criteria.
• Builder. Writes code or transforms data, then self checks with tests.
• Critic. Verifies outputs against rules and reports violations.

The orchestrator merges their reports and writes a single note. Your Claude agent stays focused on synthesis.

9. Operational Playbook: Tests, Rules, And Safety Nets

Production agents live or die on boring discipline. Add these habits early.

9.1 Define Rules That Can Fail

Give outputs a contract.

• For code, lint with strict settings and run a tiny smoke test.
• For documents, assert required sections and maximum length.
• For data, validate schema and ranges.

When a rule fails, the Claude agent should fix it or log a crisp error.

9.2 Prefer Code For Precision

Wherever possible, ask the model to express work as code. Code is testable, composable, and repeatable. A spreadsheet generated by a script beats one produced by freeform text.

9.3 Visual Feedback For Visual Tasks

If the agent produces HTML or images, render and screenshot. Ask the model to compare the screenshot against the spec. That quick loop catches layout issues that words miss.

9.4 Keep Tools Minimal

Every tool increases ambiguity. Merge overlapping behaviors. Name tools so a junior engineer can guess their input and output. The Claude agent will choose better when choices are obvious.

9.5 Log, Then Learn

Save short traces for failures. Include the prompt, selected tools, and the rule that failed. Review a handful each week. Adjust instructions and tighten tools. Ship small fixes often. Your Claude agent will feel calmer with time.

10. Practical Walkthrough: From Idea To Daily Use

Let’s turn the patterns into a simple daily flow you can adopt in under an hour.

10.1 Set Up The Project

• Create the folder layout shown earlier.
• Add the memory helpers and the save_note_to_memory tool.
• Create the orchestrator with a system prompt that says: consult memory first, summarize at the end.

10.2 Run A First Task

• Ask the Claude agent to draft a two paragraph product brief for a feature.
• Expect it to call save_note_to_memory with the decisions it made.
• Open memory/NOTES.md and confirm the summary looks useful tomorrow.

10.3 Add A Sub-Agent

• Create a small “researcher” as above.
• Have the orchestrator call it when the user goal contains “investigate,” “compare,” or “why.”
• Ensure the researcher writes a short report with links and nothing else.

10.4 Add Compaction

• After five turns, summarize the conversation into a single section in NOTES.md.
• Keep the latest plan and the next step. Archive the rest to memory/decisions/.

Once you reach this point, the Claude agent starts to feel like a partner. It remembers what you agreed on. It cites where it looked. It tells you what it will do next.

11. Design Principles That Keep Agents Sane

A few guardrails keep you from overthinking.

• Bias To Fewer Tokens. Ask “does this line help the next action.” If not, cut it.
• Prefer Names Over Narratives. File names, paths, and timestamps beat long prose.
• One Page Notes. If a note gets long, split it into a page with a short index.
• Short Plans. Five steps are enough for most tasks. Let the model refine as it goes.
• Tight Feedback. Fail fast on rules, fix, and move on.

Guardrails stop the Claude agent from drift and keep the context sharp.

12. When To Reach For Extra Infrastructure

Not every team needs a vector database on day one. Reach for one when:

• Memory files grow past a few megabytes.
• You need fuzzy search across many topics.
• Latency matters more than perfect recall.

Start simple. Add structure when you feel pain. A Claude agent with crisp files and good names often beats a complex stack that nobody maintains.

13. Common Failure Modes And How To Fix Them

• Bloated Toolbox. Merge tools that overlap. Keep the primary verbs obvious.
• Endless History. Summarize after a handful of turns. Archive raw traces.
• Vague System Prompt. State the contract in short lines. Tell the agent to consult memory first and save a note at the end.
• No Source Paths. Require the agent to cite the file paths or URLs behind every claim.
• Silent Errors. Throw on validation failures. Then fix or ask for help in one turn.

Ship these fixes and your Claude agent will feel robust within a week.

14. The Payoff: From Goldfish To Partner

The reason this works is not magic. It is craft. You give the system tools that map to real work, then you engineer the context with the same care you give your code. The result is a Claude agent that carries intent across days, freezes decisions into notes, and spends its tokens on the next action, not on re-explaining the past.

Here is the mindset to keep:

• Treat context like RAM you manage.
• Treat notes like nonvolatile storage you curate.
• Treat tools like APIs with contracts.
• Treat verification like tests that fail loudly.

You now have a Claude agent that remembers what you decided, why you decided it, and what to do next. That is the whole point of long-term memory AI.

Closing: Build The Agent You Wish You Had

You do not need a giant architecture to get real value. Start with a folder, a note tool, and a three beat loop. Add a small researcher. Add compaction when you feel the squeeze. Name things well. Keep the rules short and the outputs testable.

If you want momentum tomorrow, build your Claude agent today. Use the Claude agent sdk to wire up the tools your work demands. Teach the system to write notes you would be proud to hand a teammate. Then run it on your next real task and watch how much time you save.

Call to action. Pick one project. Add memory, a save note tool, and a five line system prompt. Run the loop. Ship something small by tonight. Then grow it one rule at a time. Your future self, and your Claude agent, will thank you.