Forem: web3nomad.eth

ClawdBot's Hidden Superpower (It's Not Working While You Sleep)

web3nomad.eth — Sun, 25 Jan 2026 14:59:16 +0000

I installed ClawdBot 36 hours ago. Like thousands of others who saw it explode across X, I got caught up in the excitement—the promise of a "24/7 AI assistant" that works while you sleep sounded irresistible.

But after watching my instance run for a day and a half, and reading through hundreds of posts from early adopters, I noticed something fascinating: the people getting the most value from ClawdBot aren't the ones trying to make it work 24/7. They're the ones who figured out what it's actually good at.

This isn't a takedown. ClawdBot is genuinely innovative—just not in the way the viral tweets suggest.

Why Everyone (Including Me) Got Excited

The narrative was perfect.

@AlexFinn: "It built a full project management system for me while I slept."

@bffmike: "It coded all night while I slept, woke up to progress."

@leopoldfeldman bought 16 Mac Minis to run multiple instances, calling it his "personal AI data center."

Who wouldn't want that? An AI that works while you rest. No overtime, no complaints, just pure output accumulating overnight. It's the productivity fantasy we've all had at 11 PM staring at an unfinished project.

The FOMO was real. Within 48 hours, Mac Mini jokes flooded timelines. People scrambled to set it up, terrified of missing "the future."

I was one of them.

What I Actually Found

Here's what happened in my first 36 hours:

Hour 0-12: Excitement. Set it up to "monitor my projects" overnight.

Hour 12-24: Woke up to... a lot of activity. Messages, updates, suggestions. Impressive volume.

Hour 24-36: Spent 2 hours reviewing what it did. Some useful, some needed correction, some I just... didn't need at 3 AM.

Then I started looking at how other people were actually using it.

@bangkokbuild's setup caught my attention:

Monitors earthquakes in Tokyo
Tracks website visitor analytics
Checks in if he's been quiet too long
Logs sleep and health data, alerts when he stays up late
Morning brief: weather + health stats + calendar

@danpeguine's approach:

Scans RSS feeds for key trends
Removes spam from incoming mail
Sends notifications about his son's school tests

@dreetje:

Checks incoming mail and removes spam
Keeps track of costs and splits them after trips

Notice something? They're not asking it to produce constantly. They're asking it to watch constantly.

That's when it clicked.

The Shift: From Worker to Watcher

The viral posts emphasize "output while you sleep"—the image of AI cranking out deliverables as you rest. Blog posts written. Code shipped. Projects built.

But look at what actually works:

The people who figured out ClawdBot aren't using it as a overnight shift worker. They're using it as a vigilance system.

It's the difference between asking someone to write ten reports while you're gone versus asking them to text you if something important happens.

One generates volume. The other generates signal.

Think about @bangkokbuild's earthquake monitoring. That's not "work 24/7." That's "wait 24/7, act when it matters." The AI spends 99.9% of its time doing nothing—just watching seismic data feeds. Then, the instant something triggers, it alerts him.

Compare that to "write me 10 blog posts overnight":

You get 10 drafts
You spend morning reading and revising all 10
Maybe 2 are usable
The rest was just... activity

The earthquake monitor:

Costs almost nothing (just API calls for data checks)
Requires zero morning review
Delivers actual value (you know if there was an earthquake)

The irony: The most valuable 24/7 AI assistant is the one that barely does anything most of the time.

The Real Innovation (That Everyone's Missing)

Here's what ClawdBot actually breakthrough:

1. Persistent Context

It remembers yesterday's conversation. You can @mention it today, and it knows what you meant yesterday. No "previously on..." recap needed. This is huge, but it's not about 24/7 operation—it's about zero context-switching cost.

2. Lives Where You Already Are

Telegram. WhatsApp. Discord. You don't open a separate app or remember to check a dashboard. It's already in your pocket, in the chat apps you open 50 times a day.

3. Always Accessible

This is the real "24/7" value. Not that it's always working, but that it's always reachable. You're on a walk, you think of something, you message it. No laptop needed. No "let me write this down for later."

Notice none of these are about continuous labor. They're all about availability without friction.

The comparison isn't "human assistant who sleeps 8 hours" vs "AI that works 24 hours."

The comparison is "I need to open my laptop, find the right window, remember context" vs "I'm already in Telegram, I just @ it."

Why This Matters

We're still learning what AI is actually good at. And there's a pattern to how we learn:

Phase 1: See the capability. Get excited about maximum throughput. ("It can generate! Make it generate everything!")

Phase 2: Realize the overhead. ("Wait, I'm spending more time reviewing AI output than I would've spent just doing it myself.")

Phase 3: Find the efficient equilibrium. ("Oh, it's best at X, not Y.")

ClawdBot early adopters are speedrunning from Phase 1 to Phase 3.

The people who figured it out aren't trying to maximize AI labor. They're trying to maximize their own attention. They're deploying ClawdBot where vigilance is valuable but human attention is expensive.

Monitoring earthquakes: valuable vigilance, expensive attention.
Scanning RSS feeds for specific keywords: valuable vigilance, expensive attention.
Tracking whether you replied to an important email: valuable vigilance, expensive attention.

Writing 10 blog posts overnight: expensive AI compute, still expensive human attention (to review).

The Cost Reality (Without Judgment)

Federico Viticci ran ClawdBot for one week. His instance consumed 180 million Anthropic API tokens.

That's roughly $360 if you're paying per token. He's on Claude Max, but most people aren't.

I'm not saying this to criticize Federico—his use case probably justified it. But it illustrates something important:

When you ask AI to "work overnight," you're asking it to think continuously. And continuous thinking costs continuous tokens.

Compare that to the monitoring use cases:

Check RSS feed every 10 minutes: minimal tokens
Wait for earthquake data trigger: minimal tokens
Scan incoming email for spam: minimal tokens

The most efficient ClawdBot users stumbled into this naturally. Not because they were optimizing for cost, but because they were optimizing for signal.

Turns out those two optimizations align perfectly.

What This Tells Us About AI Adoption

Every transformative tool goes through this curve. The printing press. Electricity. The internet.

First reaction: Do everything we did before, but with the new tool.

Printing press → print books that look like hand-copied manuscripts
Early websites → digital versions of print brochures
Early AI → ChatGPT as a faster Google

Second reaction: Do more of everything.

More books! More web pages! More AI output!

Third reaction: Wait, what's this actually good at?

Books become different (novels, newspapers, pamphlets)
Websites become interactive, not just informative
AI becomes... we're figuring this out right now

ClawdBot's viral moment is us cycling through reactions one and two. The people getting real value have landed on three.

And reaction three looks like: AI as an always-on sensor network, not an always-on labor force.

The Future Is On-Call, Not Always-On

The best AI tools won't be the ones that work 24/7.

They'll be the ones that know when to interrupt you and when to stay quiet.

When to wake you up for an earthquake and when to let you sleep through another crypto price fluctuation.

When to flag an email that needs your attention now and when to just archive the newsletter you never read.

When to suggest a better approach to your code and when to let you work through the problem yourself.

ClawdBot gets us closer to that future—not because it never sleeps, but because it's always reachable when we need it.

The people who figured this out aren't using it as a replacement for their own thinking. They're using it as an extension of their attention span—a way to keep an eye on things that matter without actually keeping an eye on them.

That's the real innovation.

Not that it works while you sleep. But that it watches while you live.

The pattern I'm seeing: The tools we'll still be talking about in 2027 won't be the ones that "do more." They'll be the ones that help us do less—but better.

ClawdBot is one of them. Just not for the reasons going viral.

How We Migrated atypica.AI to AI SDK v5 Without Breaking 10M+ Chat Histories

web3nomad.eth — Sun, 18 Jan 2026 04:29:18 +0000

atypica.AI is a multi-agent research platform where AI agents collaborate to conduct user research. Users ask business questions, and the system orchestrates multiple specialized agents—Study Agent plans research, Scout Agent discovers target users from social media, Interview Agent conducts automated interviews with AI personas, and Report Agent generates comprehensive insights. The entire process involves 30+ AI tools and generates extensive chat histories stored in PostgreSQL.

When Vercel released AI SDK v5 with breaking changes to message formats and tool APIs, we faced a challenge: migrate 200 files and 30+ tools while keeping 10 million+ existing chat conversations accessible. This article documents our 3-day migration journey.

Final stats: 200 files changed, 4,206 insertions, 3,094 deletions, 27 commits.

The Core Breaking Change: Message → UIMessage

The most fundamental change in v5 is how messages are structured.

v4: Message with content + parts

// v4 Message
{
  id: "msg1",
  role: "assistant",
  content: "The weather is sunny",  // String representation
  parts: [                           // Structured data (optional)
    { type: "text", text: "The weather is " },
    { type: "tool-invocation", toolInvocation: { ... } },
    { type: "text", text: "sunny" }
  ]
}

In v4, you could use either content (simple string) or parts (structured array). Most of our code used content because it was simpler.

v5: UIMessage with parts only

// v5 UIMessage
{
  id: "msg1",
  role: "assistant",
  parts: [                           // Only source of truth
    { type: "text", text: "The weather is " },
    { type: "tool-getWeather", toolCallId: "...", state: "output-available", output: {...} },
    { type: "text", text: "sunny" }
  ],
  content: "The weather is sunny"   // Auto-generated, read-only
}

In v5, parts is the only source of truth. The content field is automatically derived from parts and is read-only.

Migration impact: Every place that accessed message.content needed to be refactored to iterate through message.parts.

Day 1: Understanding the Scope

Running the Codemod

npm install ai@^5.0.59 zod@^4.0.0
npx @ai-sdk/codemod@latest upgrade

The codemod handled mechanical replacements:

Type name: Message → UIMessage
Tool API: parameters → inputSchema
Added outputSchema placeholders

But it left many FIXME comments because it couldn't understand semantic changes.

The First Major Problem: Content Access

We had code like this everywhere:

// v4 pattern - accessing content directly
const lastMessage = messages[messages.length - 1];
if (lastMessage.content.includes("weather")) {
  // ...
}

// For title generation
const title = message.content.substring(0, 50);

// For logging
logger.info({ userMessage: message.content });

v5 migration: We created a utility to extract text from parts:

// messageUtils.ts
export function getTextFromParts(parts: UIMessage["parts"]): string {
  return parts
    .filter((part) => part.type === "text")
    .map((part) => part.text)
    .join("");
}

// Usage
const text = getTextFromParts(message.parts);
if (text.includes("weather")) {
  // ...
}

This pattern appeared in:

Message persistence (16 files)
UI components (25 files)
API routes (15 files)
Logging and analytics (8 files)

Tool Invocation Structure Changed

This was the second major breaking change.

v4 tool part structure:

{
  type: "tool-invocation",
  toolInvocation: {
    state: "result",
    toolCallId: "call_123",
    toolName: "searchPersonas",
    args: { query: "coffee lovers" },
    result: { personas: [...] }
  }
}

v5 tool part structure:

{
  type: "tool-searchPersonas",      // Typed as tool-${toolName}
  toolCallId: "call_123",
  state: "output-available",        // States renamed
  input: { query: "coffee lovers" }, // args → input
  output: { personas: [...] }        // result → output
}

Key changes:

Flattened structure (no nested toolInvocation object)
Type is specific: "tool-${toolName}" not generic "tool-invocation"
State names: "call" → "input-available", "result" → "output-available"
Field names: args → input, result → output
Added error state: "output-error" with errorText

Reasoning Format Changed

// v4
{ type: "reasoning", reasoning: "Let me think..." }

// v5
{ type: "reasoning", text: "Let me think..." }

Field name changed from reasoning to text.

Day 2: Backward Compatibility for 10M+ Messages

The Database Challenge

Our PostgreSQL database stores messages in v4 format:

SELECT parts FROM chat_messages WHERE id = 'msg_old';
-- Returns v4 format with tool-invocation and reasoning fields

Users expect to:

Open old chat conversations
Continue conversations seamlessly
See tool results from old interactions

We couldn't migrate the database because:

10M+ messages across 50+ tables
Downtime was unacceptable
Risk of data corruption too high

Solution: Conversion Layer

Created src/ai/v4.ts:

export type V4ToolInvocation =
  | { state: "call"; toolCallId: string; toolName: string; args: any }
  | { state: "result"; toolCallId: string; toolName: string; args: any; result: any };

export type V4MessagePart =
  | { type: "text"; text: string }
  | { type: "reasoning"; reasoning: string } // v4 format
  | { type: "tool-invocation"; toolInvocation: V4ToolInvocation };

export type V5MessagePart = UIMessage["parts"][number];

export function convertToV5MessagePart(part: V4MessagePart | V5MessagePart): V5MessagePart {
  // Text parts are identical in v4 and v5
  if (part.type === "text") {
    return part;
  }

  // Reasoning: reasoning field → text field
  if (part.type === "reasoning") {
    if ("reasoning" in part) {
      return { type: "reasoning", text: part.reasoning };
    }
    return part; // Already v5
  }

  // Tool invocation: nested → flat, args/result → input/output
  if (part.type === "tool-invocation" && "toolInvocation" in part) {
    const inv = part.toolInvocation;
    return {
      type: `tool-${inv.toolName}`,
      toolCallId: inv.toolCallId,
      state: inv.state === "result" ? "output-available" : "input-available",
      input: inv.args,
      output: inv.state === "result" ? inv.result : undefined,
    } as V5MessagePart;
  }

  // Already v5 format
  return part as V5MessagePart;
}

Apply Conversion on Read

// messageUtils.ts
export async function convertDBMessagesToAIMessages(userChatId: string): Promise<UIMessage[]> {
  const dbMessages = await prisma.chatMessage.findMany({
    where: { userChatId },
    orderBy: { createdAt: "asc" },
  });

  return dbMessages.map((msg) => ({
    id: msg.messageId,
    role: msg.role as "user" | "assistant",
    parts: (msg.parts as V4MessagePart[]).map(convertToV5MessagePart),
  }));
}

Result: Old messages load transparently. New messages save in v5 format. No database migration needed.

Type System Reorganization

We have 5 independent chat systems with different tools:

Study: 20+ tools (reasoning, search, interviews, reports, social media)
Interview: 2 tools (endInterview, requestInteractionForm)
Persona: 1 tool (endInterview)
NewStudy: 1 tool (endInterview)
Agents: 3 tools (thanks, hello, scout)

Initial approach: One global UIToolConfigs type.

Problem: Type pollution. Study components got autocomplete for Interview tools. Runtime errors from tool type mismatches.

Solution: Domain-specific tool types.

// src/ai/tools/types.ts - Study system
export type StudyUITools = {
  reasoningThinking: {
    input: z.infer<typeof reasoningThinkingInputSchema>;
    output: z.infer<typeof reasoningThinkingOutputSchema>;
  };
  searchPersonas: {
    input: z.infer<typeof searchPersonasInputSchema>;
    output: z.infer<typeof searchPersonasOutputSchema>;
  };
  // ... 20+ other tools
};

export type TStudyMessageWithTool = UIMessage<unknown, UIDataTypes, StudyUITools>;

// src/app/(interviewProject)/tools/types.ts - Interview system
export type TInterviewUITools = {
  endInterview: {
    input: z.infer<typeof endInterviewInputSchema>;
    output: z.infer<typeof endInterviewOutputSchema>;
  };
  requestInteractionForm: {
    input: z.infer<typeof requestInteractionFormInputSchema>;
    output: z.infer<typeof requestInteractionFormOutputSchema>;
  };
};

export type TInterviewMessageWithTool = UIMessage<unknown, UIDataTypes, TInterviewUITools>;

Each domain gets its own directory structure:

src/app/(myDomain)/
├── tools/
│   ├── types.ts    # Tool type definitions
│   └── ui.tsx      # Tool UI rendering
└── types.ts        # Message type for this domain

Benefit: Full type safety within each domain. No cross-contamination.

Day 3: UI Components and Model Messages

Component Migration Pattern

Before v5, components accessed content directly:

// v4 component
export function ChatMessage({ message }: { message: Message }) {
  return <div>{message.content}</div>;
}

After v5, components iterate over parts:

// v5 component
export function ChatMessage({ message }: { message: UIMessage }) {
  return (
    <div>
      {message.parts.map((part, i) => {
        if (part.type === "text") {
          return <Markdown key={i}>{part.text}</Markdown>;
        } else if (part.type === "reasoning") {
          return <ReasoningBlock key={i}>{part.text}</ReasoningBlock>;
        } else if (part.type.startsWith("tool-")) {
          return <ToolDisplay key={i} toolPart={part} />;
        }
      })}
    </div>
  );
}

Tool detection pattern:

// v4
if (part.type === "tool-invocation") {
  const toolName = part.toolInvocation.toolName;
  const result = part.toolInvocation.result;
}

// v5
if (part.type.startsWith("tool-") && "toolCallId" in part) {
  const toolName = part.type.replace("tool-", "");
  const output = part.state === "output-available" ? part.output : undefined;
}

We migrated 25+ UI components with this pattern.

The UIMessage vs ModelMessage Distinction

There's one more important detail: messages to the model have a different format.

UIMessage - From model, for UI:

{
  role: "user",
  parts: [{ type: "text", text: "Hello" }]
}

UserModelMessage - To model:

{
  role: "user",
  content: [{ type: "text", text: "Hello" }]  // Note: content, not parts
}

This only matters when constructing messages for streamText or generateObject:

import { UserModelMessage } from "ai";

const result = await streamText({
  model: llm("gpt-4"),
  messages: [
    {
      role: "user",
      content: [{ type: "text", text: prompt }]  // content for model
    }
  ] as UserModelMessage[],
  tools: { ... }
});

We had to fix this in 30+ tool definitions and artifact generators.

useChat Hook Changes

// v4
const { append, reload, initialMessages } = useChat({
  id: chatId,
  experimental_prepareRequestBody({ messages, requestBody }) {
    return { message: messages[messages.length - 1], ...requestBody };
  },
});

// v5
const { sendMessage, regenerate, messages } = useChat({
  transport: new DefaultChatTransport({
    api: "/api/chat/study",
    prepareSendMessagesRequest({ id, messages }) {
      return {
        body: {
          id,
          message: messages[messages.length - 1],
          userChatToken: token,
        },
      };
    },
  }),
});

Hook method renames:

append → sendMessage
reload → regenerate
initialMessages → messages

Transport config:

experimental_prepareRequestBody → prepareSendMessagesRequest

File Attachments

// v4
{
  experimental_attachments: [{ name: "file.pdf", contentType: "application/pdf", url: "..." }];
}

// v5 - part of parts array
{
  parts: [{ type: "file", filename: "file.pdf", mediaType: "application/pdf", data: "..." }];
}

Field renames:

name → filename
contentType → mediaType
experimental_attachments → part of parts array

Streaming Message Persistence

Key insight: In v5, only check parts.length, not content.

// v4 - check both
if (streamingMessage.parts?.length && streamingMessage.content.trim()) {
  await persistentAIMessageToDB(userChatId, streamingMessage);
}

// v5 - only check parts
if (streamingMessage.parts?.length) {
  await persistentAIMessageToDB(userChatId, streamingMessage);
}

The content field in v5 is derived from parts, so checking it is redundant.

Critical Gotchas

1. Message Content is Read-Only in v5

// v4 - this worked
message.content = "New text";

// v5 - this does nothing (content is derived)
message.content = "New text"; // ❌ Silently ignored

// v5 - correct way
message.parts = [{ type: "text", text: "New text" }]; // ✅

2. Empty Parts vs Empty Content

// v4
if (message.content) { ... }

// v5 - this can be misleading
if (message.content) { ... }  // content is auto-generated, might be empty string

// v5 - correct check
if (message.parts.some(p => p.type === "text" && p.text)) { ... }

3. Tool State Names Changed

// v4 states
"partial-call" | "call" | "result";

// v5 states
"input-available" | "output-available" | "output-error";

Don't forget to update all state checks.

4. Optional Tool Call Names

In edge cases (aborted streams, errors), toolCall.toolName might be undefined:

// Safe access
step.toolCalls.map((call) => call?.toolName ?? "unknown");

5. Stream Event Field Names

// v4
onFinish: async ({ reasoning, text, usage }) => {};

// v5
onFinish: async ({ reasoningText, text, usage }) => {};

6. Message ID Handling

Client messages might not have IDs:

await persistentAIMessageToDB(userChatId, {
  ...newMessage,
  id: newMessage.id ?? generateId(),
});

Migration Checklist

Phase 1: Dependencies

[ ] Update ai to v5, zod to v4
[ ] Run codemod: npx @ai-sdk/codemod@latest upgrade
[ ] Fix TypeScript errors from Message → UIMessage rename

Phase 2: Content Access

[ ] Find all message.content access
[ ] Replace with parts iteration or utility function
[ ] Update title generation, logging, analytics

Phase 3: Tool Parts

[ ] Update tool detection: "tool-invocation" → part.type.startsWith("tool-")
[ ] Change field access: args/result → input/output
[ ] Update state checks: "call"/"result" → "input-available"/"output-available"
[ ] Add "output-error" handling

Phase 4: Backward Compatibility

[ ] Create v4 → v5 conversion utility
[ ] Apply conversion when loading from database
[ ] Test old chat histories thoroughly

Phase 5: UI Components

[ ] Migrate all components to iterate over parts
[ ] Update tool rendering logic
[ ] Update file attachment components

Phase 6: Tool Definitions

[ ] Change parameters → inputSchema
[ ] Add outputSchema
[ ] Import UserModelMessage for model messages
[ ] Use content (not parts) when calling streamText/generateObject

Phase 7: React Hooks

[ ] Update useChat: append → sendMessage, reload → regenerate
[ ] Migrate experimental_prepareRequestBody → prepareSendMessagesRequest

Phase 8: Edge Cases

[ ] Handle missing message IDs
[ ] Handle undefined toolCall.toolName
[ ] Update stream event handlers
[ ] Remove content.trim() checks

Key Insights

1. Content is Dead, Long Live Parts

The shift from content as source of truth to parts as source of truth is fundamental. Every message access pattern needs review.

Budget time for:

Finding all message.content references (use global search)
Understanding each usage context
Deciding between iteration or utility function

2. The Codemod is 30% of the Work

The codemod handles:

Type renames
Basic API changes
Obvious field renames

It doesn't handle:

Semantic changes (content access patterns)
Complex refactors (tool detection logic)
Domain-specific decisions (type organization)

Budget 70% of time for post-codemod fixes.

3. Backward Compatibility is Non-Negotiable

Users don't care about your migration. Their old chats must just work.

Strategies:

Convert on read (what we did)
Convert on write (gradual migration)
Dual schema (complex but zero risk)

We chose convert-on-read because:

Zero downtime
Simple to implement
Low risk
Works transparently

4. Type System Organization Matters

With multiple chat systems, proper type organization prevents:

Tool type pollution
Runtime errors from wrong tool usage
Confusing autocomplete

Invest time in domain-specific types early.

5. Test Incrementally

We migrated systems in order of complexity:

Agents (simplest, 3 tools) - validate pattern
NewStudy (1 tool) - test in production
Persona (1 tool) - confidence building
Interview (2 tools) - more complex
Study (20+ tools) - final boss

Each system validated the patterns before applying them broadly.

Results

Before v5:

Inconsistent access patterns (content vs parts)
Loose typing around tools
Message type used everywhere

After v5:

Single source of truth: parts array
Full type safety across 30+ tools
Domain-specific type organization
Cleaner separation of concerns

Time breakdown:

Day 1: Dependencies, codemod, content access patterns (8 hours)
Day 2: Backward compatibility, type system (10 hours)
Day 3: UI components, tool definitions, edge cases (6 hours)

Total: ~24 hours focused work over 3 days.

Recommendations

Budget 3-5 days, not 1-2 days
Start simple: Migrate your simplest system first
Build backward compatibility early, not as afterthought
Create utilities: getTextFromParts(), convertV4ToV5(), etc.
Organize types by domain if you have multiple systems
Test old data: Load historical chats, verify tool results display
Document the change: Team needs to understand parts is source of truth

The migration is substantial but manageable with proper planning. v5's parts-based approach is more flexible and type-safe. The pain of migration is short-term; the benefits are long-term.

Universal Agent + Skills Tutorial: Build Your 10-Person Team from Scratch

web3nomad.eth — Sat, 17 Jan 2026 05:52:20 +0000

Universal Agent + Skills Tutorial: Build Your 10-Person Team from Scratch

Imagine this:

You tell your AI Agent: "Write me technical documentation." It instantly loads technical-writer.skill and transforms into a tech writer.

Next moment: "Analyze our competitors' ad strategies." It swaps in marketing-analyst.skill and starts crawling data.

Even better: Need an expert in a niche domain—say, "SQL performance tuning"—but can't find one? Let the Agent write a skill for itself.

This isn't sci-fi. And it's ridiculously simple to build.

This guide shows you how to build a Universal Agent:

✅ Load any skill - Drop in a .skill file, Agent instantly gains new capabilities
✅ Self-authoring skills - Agent can create specialized skill packages for itself
✅ Persistent work - Files survive across conversations—code from morning, iterate in afternoon
✅ Zero infrastructure - No Docker, no K8s. Just a Next.js project.

Think of it as assembling a 10-person founding team: each skill is a specialist, the Agent is the PM, you're the CEO.

Architecture

User uploads skill packages → S3 storage
                                ↓
Request starts → Load skills + workspace → In-memory sandbox
                                ↓
Agent reads skills, creates files, uses tools
                                ↓
Request ends → Save workspace changes → Disk
                                ↓
Next conversation → Files persisted → Agent continues work

Key components:

bash-tool - In-memory filesystem with bash, readFile, writeFile
Skills in sandbox/user/{id}/skills/ (read-only, from S3)
Workspace in sandbox/user/{id}/workspace/ (read-write, persisted)
AI SDK handles streaming, tool calls, token tracking

Core Implementation

1. Skill Structure

Each skill is a .skill file (zip format) with a simple structure:

my-skill/
├── SKILL.md          # Instructions and expertise
└── references/       # Optional: supporting docs
    └── examples.md

Example SKILL.md:

---
name: technical-writer
description: Creates technical documentation, API guides, and tutorials.
---

# Technical Writer Skill

You are an expert technical writer who creates clear, concise documentation.

## Expertise
- API documentation with examples
- Architecture decision records (ADRs)
- User guides and tutorials
- Code comments and inline docs

## Guidelines
- Start with why, then what, then how
- Include practical examples
- Use active voice
- Keep it DRY—link instead of repeating

## Activation
Activate when user asks to:
- "Write documentation for..."
- "Create an API guide..."
- "Document this codebase..."

Upload flow: User uploads zip → Store in S3 → Reference in database → Agent loads on demand.

2. Core Route Handler

File: app/api/chat/universal/route.ts

import { streamText } from "ai";
import { createBashTool } from "bash-tool";
import { loadAllSkillsToMemory } from "@/lib/skill/loadToMemory";
import { loadUserWorkspace, saveUserWorkspace } from "@/lib/skill/workspace";

export async function POST(req: Request) {
  const { userId, userChatId } = await authenticate(req);

  // Load skills from S3/disk
  const skills = await prisma.agentSkill.findMany({ where: { userId } });
  const skillFiles = await loadAllSkillsToMemory(skills);

  // Load persisted workspace
  const workspaceFiles = await loadUserWorkspace(userId);

  // Prefix skills for isolation
  const skillFilesWithPrefix = Object.fromEntries(
    Object.entries(skillFiles).map(([path, content]) => [`skills/${path}`, content])
  );

  // Create sandbox
  const { tools: bashTools, sandbox } = await createBashTool({
    files: {
      ...workspaceFiles,         // User's work (root directory)
      ...skillFilesWithPrefix,   // Skills (skills/ subdirectory)
    },
  });

  // Merge with other tools
  const tools = {
    ...baseTools,              // webSearch, reasoningThinking, etc.
    bash: bashTools.bash,
    readFile: bashTools.readFile,
    writeFile: bashTools.writeFile,
    exportFolder: exportFolderTool({ sandbox, userId }),
  };

  // Stream with persistence
  const result = streamText({
    model: llm("claude-sonnet-4-5"),
    system: buildSystemPrompt({ skills, locale }),
    messages: await loadMessages(userChatId, { tools }),
    tools,

    onStepFinish: async (step) => {
      await saveStepToDB(step);
      await trackTokens(step);
    },

    onFinish: async () => {
      // Persist workspace changes
      await saveUserWorkspace(userId, sandbox);
    },
  });

  return result.toUIMessageStreamResponse();
}

Key points:

Load both skills and workspace at start
Skills isolated under skills/ prefix (read-only)
Workspace in root (read-write, persisted)
onFinish saves all changes back to disk

3. Workspace Persistence

File: lib/skill/workspace.ts

import type { Sandbox } from "bash-tool";

export async function loadUserWorkspace(userId: number): Promise<Record<string, string>> {
  const workspacePath = getWorkspacePath(userId); // .next/cache/sandbox/user/{id}/workspace
  const files: Record<string, string> = {};

  await loadDirectoryRecursively(workspacePath, "", files);
  return files;
}

export async function saveUserWorkspace(userId: number, sandbox: Sandbox): Promise<void> {
  const workspacePath = getWorkspacePath(userId);

  // Get all files except skills/
  const findResult = await sandbox.executeCommand(
    `find . -type f ! -path "./skills/*" 2>/dev/null || echo ""`
  );

  const filePaths = findResult.stdout.split("\n").filter(Boolean);

  // Clear workspace and save fresh state
  await fs.rm(workspacePath, { recursive: true, force: true });
  await fs.mkdir(workspacePath, { recursive: true });

  for (const filePath of filePaths) {
    const content = await sandbox.readFile(filePath);
    const fullPath = path.join(workspacePath, filePath.replace(/^\.\//, ""));
    await fs.mkdir(path.dirname(fullPath), { recursive: true });
    await fs.writeFile(fullPath, content);
  }
}

How it works:

Load: Read all files from disk into memory
Agent works: Creates/modifies files in sandbox
Save: Extract non-skill files, write back to disk
Next request: Files reappear in sandbox

4. System Prompt

File: app/prompt/index.ts

export async function buildUniversalSystemPrompt({ userId, locale, skills }) {
  const skillsXml = skills.map(s => `
<skill>
  <name>${s.name}</name>
  <description>${s.description}</description>
  <location>skills/${s.name}/SKILL.md</location>
</skill>
  `).join('\n');

  return `You are a Universal Agent with access to specialized skills.

## Available Skills

${skillsXml}

## Workspace Structure

\`\`\`
sandbox/
├── skills/                 # Read-only skills from S3
│   ├── technical-writer/
│   └── market-researcher/
└── my-project/            # Your persistent workspace
    └── README.md
\`\`\`

## How to Use Skills

1. **Load a skill**: \`cat skills/technical-writer/SKILL.md\`
2. **Embody the role**: Follow the skill's instructions completely
3. **Use skill references**: \`cat skills/technical-writer/references/examples.md\`

## File Operations

- **Create**: \`writeFile({ path: "project/index.js", content: "..." })\`
- **Read**: \`cat project/index.js\` or \`readFile({ path: "project/index.js" })\`
- **Export**: \`exportFolder({ folderPath: "project" })\` for user download

All files in root directory persist across conversations.

## Guidelines

- Load skills when user requests specialized work
- Follow skill instructions precisely—they're your expertise
- Create files in root directory (not under skills/)
- Use bash commands for exploration (ls, find, grep, etc.)`;
}

Critical design:

Skills as XML (Claude-native format)
Clear workspace vs. skills separation
Emphasize persistence behavior
Simple, actionable instructions

Real-World Usage

Example 1: Technical Documentation

User: "Write API documentation for our payment system"

Agent:
  1. cat skills/technical-writer/SKILL.md
  2. [Loads skill, embodies technical writer role]
  3. writeFile({ path: "docs/api-reference.md", content: "..." })
  4. writeFile({ path: "docs/examples.md", content: "..." })
  5. exportFolder({ folderPath: "docs" })

→ User downloads complete documentation package

Example 2: Cross-Session Work

User: "Research AI coding tools market, create report"

Agent:
  1. cat skills/market-researcher/SKILL.md
  2. webSearch({ query: "AI coding tools 2025 market analysis" })
  3. [Analyzes results, synthesizes insights]
  4. writeFile({ path: "research/market-analysis.md", content: "..." })
  5. [User stops conversation, goes to meeting]

Later:
User: "Add competitive landscape section"

Agent:
  1. cat research/market-analysis.md  # File still exists!
  2. [Continues work on existing file]
  3. writeFile({ path: "research/market-analysis.md", content: "..." })
  4. exportFolder({ folderPath: "research" })

Example 3: Agent Creates Own Skill

User: "Create a skill for SQL query optimization"

Agent:
  1. mkdir -p sql-optimizer
  2. writeFile({ path: "sql-optimizer/SKILL.md", content: "..." })
  3. writeFile({ path: "sql-optimizer/references/patterns.md", content: "..." })
  4. exportFolder({ folderPath: "sql-optimizer" })

User: Downloads, uploads as .skill file
→ Now available in skills/ directory for future use

Key Design Decisions

1. Why bash-tool?

Alternatives considered:

Direct filesystem access → Security risk
Code interpreter (Python) → Too narrow
Full VM (@vercel/sandbox) → Overkill for file operations

Why bash-tool wins:

In-memory, isolated sandbox
Familiar bash commands (ls, cat, grep, find)
No script execution (security)
Perfect for file manipulation + exploration

2. Why Separate Skills and Workspace?

✅ Current: skills/ (read-only) + workspace/ (read-write)
❌ Alternative: Everything in root directory

Problem: Agent might accidentally overwrite skills
Solution: Clear separation, explicit in prompts

3. Why Full Workspace Sync (Not Delta)?

// ❌ Delta approach: Track and save only changed files
await saveChangedFiles(changedFiles);

// ✅ Full sync: Save complete workspace state
await saveEntireWorkspace(allFiles);

Reasoning:

Simpler implementation (no change tracking needed)
Handles deletions naturally (file missing → deleted)
Performance: Workspace typically < 100 files, sync is fast
Reliability: Avoids sync drift issues

4. Why Skills as Claude XML?

<skill>
  <name>technical-writer</name>
  <description>Creates technical documentation</description>
  <location>skills/technical-writer/SKILL.md</location>
</skill>

Claude models are trained on XML structures for tools and artifacts. This format:

Native to Claude's training
Easy to parse
Extensible (add metadata without breaking)
Familiar to Claude for skill discovery

Deployment Considerations

Docker Configuration

Challenge: bash-tool uses native modules (@mongodb-js/zstd, node-liblzma) for compression.

Solution: Don't copy native modules—they're optional.

# Dockerfile
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

# Note: Native compression modules NOT copied
# - exportFolder uses jszip (pure JS)
# - just-bash has JS fallback for compression
# If you need tar -z in sandbox, uncomment:
# COPY --from=deps /app/node_modules/.pnpm/@mongodb-js+zstd@*/node_modules/@mongodb-js ./node_modules/@mongodb-js

next.config.ts:

webpack: (config, { isServer, webpack }) => {
  if (isServer) {
    // Only externalize native binaries
    config.externals.push("@mongodb-js/zstd", "node-liblzma");

    // Ignore browser-only worker.js
    config.plugins.push(
      new webpack.IgnorePlugin({
        resourceRegExp: /^\.\/worker\.js$/,
        contextRegExp: /just-bash/,
      })
    );
  }
  return config;
}

Storage Management

// Periodic cleanup of old exports
export async function cleanupOldExports() {
  const exportsDir = path.join(process.cwd(), ".next/cache/sandbox");
  const cutoff = Date.now() - 24 * 60 * 60 * 1000; // 24 hours

  for (const userId of await fs.readdir(path.join(exportsDir, "user"))) {
    const exportsPath = getExportsPath(Number(userId));
    for (const file of await fs.readdir(exportsPath)) {
      const stat = await fs.stat(path.join(exportsPath, file));
      if (stat.mtimeMs < cutoff) {
        await fs.unlink(path.join(exportsPath, file));
      }
    }
  }
}

Performance Benchmarks

Tested on M1 Mac, 50 skills, 200 workspace files:

Operation	Time	Notes
Load skills + workspace	120ms	Parallel I/O
Create 10 files	5ms	In-memory
Save workspace	80ms	Write to disk
Export folder (50 files)	150ms	Zip creation

Optimization tips:

Cache skill files across requests (same user, same skills)
Use streaming for large file exports
Compress workspace with zstd if > 1MB

What's Next?

Extend the system:

Version control: Git integration for workspace
Skill marketplace: Share skills between users
Collaborative workspaces: Multiple agents, one workspace
Skill composition: Agent loads multiple skills simultaneously
Skill inheritance: Base skills + specialized variants

The power: Every user becomes a founder with a full engineering team. Each skill is a specialist. The Agent orchestrates. The workspace persists. The possibilities compound.

Code References

Main route: src/app/(universal)/api/chat/universal/route.ts
Workspace persistence: src/lib/skill/workspace.ts
Skill loading: src/lib/skill/loadToMemory.ts
Export tool: src/app/(universal)/tools/exportFolder.ts
System prompt: src/app/(universal)/prompt/index.ts
README: src/app/(universal)/README.md

Built with Next.js 15, Vercel AI SDK, bash-tool, and Claude 4.5 Sonnet.

Building Scalable AI Agent Systems: Three Evolutions

web3nomad.eth — Sun, 11 Jan 2026 09:46:19 +0000

I. December 2025

We needed to add a new feature to atypica.AI: group discussions (discussionChat).

This should've been simple. We already had interviewChat—one-on-one conversations where users deeply engage with AI-simulated personas. Group discussion was just scaling from 1-to-1 to 1-to-many: 3-8 personas engaging simultaneously, watching perspectives collide and insights emerge.

In theory, we just needed to:

Reuse the interview logic
Adjust prompts to simulate group dynamics
Tweak the UI to show multiple speakers

The reality: We had to modify 12 files.

prisma/schema.prisma          # New Discussion table
src/ai/tools/discussionChat.ts  # New tool
src/ai/tools/saveDiscussion.ts   # Save tool
src/app/(study)/agents/studyAgent.ts     # Add tool to agent
src/app/(study)/agents/fastInsightAgent.ts  # Add again
src/app/(study)/agents/productRnDAgent.ts   # And again
... 6 more files

Worse, we discovered this:

// studyAgentRequest.ts (493 lines)
export async function studyAgentRequest(context) {
  const result = await streamText({
    model: llm("claude-sonnet-4"),
    system: studySystem(),
    messages,
    tools: {
      webSearch,
      interview,
      scoutTask,
      saveAnalyst,
      generateReport
      // ... 15 tools
    },
    onStepFinish: async (step) => {
      // Save messages
      // Track tokens
      // Send notifications
      // ... 120 lines of logic
    }
  });
}

// fastInsightAgentRequest.ts (416 lines)
// 95% identical code

// productRnDAgentRequest.ts (302 lines)
// 95% identical code

Three nearly identical agent wrappers.
Every new feature required copy-pasting across all three.
Every bug fix meant changing it three times.

That moment, we realized: something was fundamentally wrong.

Not that our code wasn't elegant.
Not that we lacked abstraction.
But that we were building AI Agent systems with traditional software engineering thinking.

This article chronicles how we escaped this trap—through three architectural evolutions, rethinking how AI Agents should be built from first principles.

II. Rethinking: What is an AI Agent?

Before refactoring, we stopped to ask a fundamental question:

What's the essential difference between AI Agents and traditional software?

The World of Traditional Software

Traditional software is built on state machines:

class ResearchSession {
  state: 'IDLE' | 'PLANNING' | 'RESEARCHING' | 'REPORTING';
  data: {
    interviews: Interview[];
    findings: Finding[];
    reports: Report[];
  };

  transition(event: Event) {
    switch (this.state) {
      case 'IDLE':
        if (event.type === 'START') this.state = 'PLANNING';
        break;
      case 'PLANNING':
        if (event.type === 'PLAN_COMPLETE') this.state = 'RESEARCHING';
        break;
      // ... more state transitions
    }
  }
}

This model's core assumptions:

State is explicit: I know exactly where I am
Transitions are deterministic: Given state + event, next state is unique
Control is precise: if-else covers all paths

This works beautifully for traditional software. But for AI Agents?

The World of AI Agents

LLMs don't work this way:

const messages = [
  { role: 'user', content: 'Want to understand young people's coffee preferences' },
  { role: 'assistant', content: 'I can help you conduct user research...' },
  { role: 'assistant', toolCalls: [{ name: 'scoutTask', args: {...} }] },
  { role: 'tool', content: 'Observed 5 user segments...' },
  { role: 'assistant', content: 'Based on observations, I suggest interviewing 18-25 coffee enthusiasts...' },
  { role: 'assistant', toolCalls: [{ name: 'interviewChat', args: {...} }] },
  // ...
];

Where's the "state" here?

Not in a state field
But in the entire conversation history

The AI infers from conversation history:

What research does the user want?
How far have we progressed?
What should happen next?

This is a completely different paradigm.

Three Core Insights

From this observation, we derived three insights that shaped our architectural evolution.

Insight 1: Conversation as State

Traditional approach: Maintain explicit state

// ❌ Traditional: Explicit state management
interface ResearchState {
  stage: 'planning' | 'researching' | 'reporting';
  completedInterviews: number;
  pendingTasks: Task[];
}

// Need synchronization: state and conversation history can diverge

AI-native approach: Infer state from conversation

// ✅ AI-native: Conversation is state
const messages = [...conversationHistory];

// AI infers state from history, no explicit sync needed
const result = await streamText({
  messages,
  // AI knows what to do
});

Why is conversation superior to state machines?

Natural alignment: LLMs work on message history natively
Strong fault tolerance: State machines are hard to recover from errors; conversations can be "rewound" and replayed
Easy extension: Adding new capabilities doesn't require modifying state graphs

Insight 2: Reasoning-Execution Separation

How humans make decisions:

Understand intent: "What am I trying to achieve?" → Clarify goals
Choose method: "How do I do it?" → Execution steps

AI Agents should follow the same pattern:

// Plan Mode: Understanding intent
"User says: want to understand young people's coffee preferences"
  → Analyze: needs qualitative research
  → Decide: use group discussion method
  → Output: complete research plan

// Study Agent: Executing plan
"Received research plan"
  → Call discussionChat
  → Analyze discussion results
  → Generate insights report

Why separate?

Reasoning needs deep thinking (use Claude Sonnet 4)
Execution needs fast response (can use smaller models)
Separation of concerns, single responsibility

Insight 3: Simple Over Precise

Facing the "AI forgetfulness" problem, we could:

Option A: Vector DB + Semantic Search

// Precise matching of relevant memories
const query_embedding = await embed(user_message);
const relevant_memories = await vectorDB.search(query_embedding, top_k=5);

✅ Precise retrieval
❌ Requires embedding, indexing, complex queries
❌ High maintenance cost

Option B: Markdown Files + Full Loading

// Simple and transparent
const memory = await readFile(`memories/${userId}.md`);
const messages = [
  { role: 'user', content: `<UserMemory>\n${memory}\n</UserMemory>` },
  ...conversationMessages
];

✅ Simple, transparent, user-editable
✅ Leverages large context windows (Claude 200K tokens)
✅ Easier to debug and understand

We chose Option B.

Why?

Context windows changed the game: User memory typically < 10K, full loading is perfectly viable
Simple solutions are more reliable: No embedding inconsistency, no retrieval failures
User control: Memory is transparent, users can view and edit

Four Design Principles

From these three insights, we distilled the core principles of our architecture:

1. Messages as Source of Truth

All important information lives in messages
Database only stores derived state (like reports, study logs)
Similar to Event Sourcing: messages are the event log

2. Configuration over Code

Use configuration to express differences
Use code to express commonalities
Avoid over-abstraction

3. AI as State Manager

Let AI manage state transitions
Don't hand-write complex state machines
Adapt to LLM's capability boundaries

4. Simple, Transparent, Controllable

Simple beats complex
Transparent beats black box
User control beats AI automation

III. Step 1: Message-Driven Architecture

v2.2.0 - 2025-12-27

Problem: Dual Source of Truth

Initially, research data was scattered across three places:

// Place 1: analyst table
const analyst = await prisma.analyst.findUnique({
  where: { id }
});
console.log(analyst.studySummary);  // "Research summary..."

// Place 2: interviews table
const interviews = await prisma.interview.findMany({
  where: { analystId: id }
});
console.log(interviews.map(i => i.conclusion));  // ["Interview 1 conclusion", "Interview 2 conclusion"]

// Place 3: messages table
const messages = await prisma.chatMessage.findMany({
  where: { userChatId }
});
// webSearch results are here

Generating reports required stitching from three places:

async function generateReport(analystId) {
  const analyst = await prisma.analyst.findUnique({
    where: { id: analystId },
    include: { interviews: true }  // JOIN!
  });

  const messages = await prisma.chatMessage.findMany({
    where: { userChatId: analyst.studyUserChatId }
  });

  // Stitch data together
  const reportData = {
    summary: analyst.studySummary,              // from analyst table
    interviewInsights: analyst.interviews.map(...),  // from interviews table
    webResearch: extractFromMessages(messages)    // from messages table
  };
}

Problems:

Data inconsistency: interviews.conclusion and interview content in messages could diverge
Partial failures: When tool calls fail, data is half-saved, hard to trace full context
Hard to extend: Adding discussionChat requires new table, new tool, new queries

Even worse, tool outputs were inconsistent:

// interviewChat: content in DB, returns reference
{
  toolName: 'interviewChat',
  output: { interviewId: 123 }  // Need another DB query
}

// scoutTaskChat: content in return value
{
  toolName: 'scoutTaskChat',
  output: {
    plainText: "Observation results...",  // Content directly returned
    insights: [...]
  }
}

Agents couldn't handle this uniformly, leading to complex code.

Solution: Messages as Single Source

Core idea: All research content flows into the message stream. Database only stores derived state.

// ✅ New architecture: Unified output format
interface ResearchToolResult {
  plainText: string;  // Human-readable summary, required
  [key: string]: any; // Optional structured data
}

// interviewChat also returns plainText
{
  toolName: 'interviewChat',
  output: {
    plainText: "Interview summary: User Zhang San mentioned...",  // ← Full content here
    interviewId: 123  // Optional: DB reference
  }
}

Key changes:

Removed 5 specialized save tools
- Deleted: saveInterview, saveDiscussion, saveScoutTask, ...
- Reason: Agents output directly to messages, no explicit save needed
Unified tool output format
- All research tools return plainText
- Agents can uniformly process all tool results
Generate studyLog on demand

   // Don't pre-save, generate when needed
   if (!analyst.studyLog) {
     const messages = await loadMessages(studyUserChatId);
     const studyLog = await generateStudyLog(messages);  // ← Generate from messages
     await prisma.analyst.update({
       where: { id },
       data: { studyLog }
     });
   }

Why This Design?

Reasoning from first principles:

Conversation as context
- LLMs need complete context to generate reports
- Message history is naturally the most complete, most natural context
- Avoids complexity of "reconstructing context from DB"
LLMs excel at extraction
- Generating structured content (studyLog) from conversations is LLM's strength
- More flexible and reliable than hand-written parsing logic
Shadow of Event Sourcing
- Message sequence = event log
- studyLog, report = derived state
- Can be replayed and regenerated anytime

Comparison with other approaches:

Approach	Pros	Cons	Why not chosen
Messages as source	Data consistent, easy to extend	Requires extra LLM call to generate studyLog	✅ Our choice
Traditional state management	Precise control	Complex state sync, hard to trace	Doesn't suit LLM non-determinism
Remove DB entirely	Extremely simple	Frontend queries difficult, history hard to manage	Need structured display
Event Sourcing	Complete history, replayable	High engineering complexity	Over-engineered for current scale

Impact

Code simplification:

Deleted files:
- src/ai/tools/saveInterview.ts
- src/ai/tools/saveDiscussion.ts
- src/ai/tools/saveScoutTask.ts
- src/ai/tools/savePersona.ts
- src/ai/tools/saveWebSearch.ts

Simplified files (28):
- Agent configs no longer need save tools
- generateReport doesn't need multi-table JOINs

Development efficiency:

Before:

Adding discussionChat:
1. Create Discussion table
2. Write discussionChat tool
3. Write saveDiscussion tool
4. Add both tools to 3 agents
5. Write discussion query logic
6. Modify generateReport query

Total: 12 files, 2-3 days

After:

Adding discussionChat:
1. Write discussionChat tool (returns plainText)
2. Add tool to agent config
3. generateReport auto-supports (reads from messages)

Total: 3 files, 2-3 hours

Cost trade-offs:

✅ Benefits:

Simplified architecture: deleted 5 tools, simplified 28 files
Data consistency: full context traceable even on failures
Easy extension: adding new research methods goes from 12 steps → 3 steps

❌ Costs:

studyLog generation requires extra LLM call (~2K tokens, ~$0.002)
Slightly higher token consumption for long conversations

✅ Mitigation:

Prompt cache reduces repeated token cost by 90%
Architectural benefits far outweigh costs

III. Step 2: Intent Clarification + Unified Execution

v2.3.0 - 2026-01-06

Problem 1: Vague Requirements → Inefficient Dialogue

After implementing message-driven architecture, adding features became simpler. But user experience wasn't good enough.

When creating research, users often say:

"Want to understand young people's coffee preferences"

This isn't specific enough:

Which young people? 18-22 college students? Or 23-28 young professionals?
What method? In-depth interviews? Group discussions? Or social media observation?
What output? User personas? Market insights? Or product recommendations?

Traditional approach: AI asks multiple questions

AI: "Which age group do you want to research?"
User: "18-25 I guess"
AI: "What method? Interviews or surveys?"
User: "Interviews"
AI: "How many people?"
User: "Around 10"

Problems:

Requires 3-5 conversation rounds
Poor user experience (feels like filling forms)
AI can't proactively suggest best approaches

Problem 2: 95% Duplicate Code

While adding features became simpler, we discovered a bigger technical debt:

$ wc -l src/app/(study)/agents/*AgentRequest.ts
493 studyAgentRequest.ts
416 fastInsightAgentRequest.ts
302 productRnDAgentRequest.ts

Three nearly identical agent wrappers, totaling 1,211 lines.

Code duplication mainly in:

Message loading and processing (~80 lines each)
File attachment handling (~60 lines each)
MCP integration (~40 lines each)
Token tracking (~50 lines each)
Notification sending (~30 lines each)

Every new feature (like webhook integration) required changing all three places.

Solution: Plan Mode + baseAgentRequest

Our solution has two parts:

Part 1: Plan Mode (Intent Clarification Layer)

A separate agent dedicated to intent clarification:

// src/app/(study)/agents/configs/planModeAgentConfig.ts

export async function createPlanModeAgentConfig() {
  return {
    model: "claude-sonnet-4-5",
    systemPrompt: planModeSystem({ locale }),
    tools: {
      requestInteraction,  // Interact with user
      makeStudyPlan,       // Display complete plan, one-click confirm
    },
    maxSteps: 5,  // Max 5 steps to complete clarification
  };
}

Workflow:

sequenceDiagram
    participant User
    participant PlanMode as Plan Mode Agent
    participant StudyAgent as Study Agent

    User->>PlanMode: "Want to understand young people's coffee preferences"

    PlanMode->>PlanMode: Analyze requirements
    Note over PlanMode: - Target: 18-25 years old<br/>- Research type: qualitative insights<br/>- Best method: group discussion

    PlanMode->>User: Display complete plan
    Note over PlanMode,User: 【Research Plan】<br/>Goal: Understand 18-25 coffee preferences<br/>Method: Group discussion (5-8 people)<br/>Duration: ~40 minutes<br/>Output: Consumer insights report<br/><br/>[Confirm Start] [Modify Plan]

    User->>PlanMode: [Confirm Start]

    PlanMode->>StudyAgent: Intent recorded in messages
    Note over StudyAgent: Read intent from conversation history<br/>Execute research plan

    StudyAgent->>User: Start research execution

Key design:

Plan Mode's decisions are recorded in messages
Study Agent infers intent from messages, no explicit passing needed
Avoids complexity of context passing

Part 2: baseAgentRequest (Unified Executor)

Merge three duplicate agent wrappers into one generic executor:

// src/app/(study)/agents/baseAgentRequest.ts (577 lines)

interface AgentRequestConfig<TOOLS extends ToolSet> {
  model: LLMModelName;
  systemPrompt: string;
  tools: TOOLS;
  maxSteps?: number;

  specialHandlers?: {
    // Dynamically control which tools are available
    customPrepareStep?: (options) => {
      messages,
      activeTools?: (keyof TOOLS)[]
    };

    // Custom post-processing logic
    customOnStepFinish?: (step, context) => Promise<void>;
  };
}

async function executeBaseAgentRequest<TOOLS>(
  baseContext: BaseAgentContext,
  config: AgentRequestConfig<TOOLS>,
  streamWriter: UIMessageStreamWriter
) {
  // Phase 1: Initialization
  // Phase 2: Prepare Messages
  // Phase 3: Universal Attachment Processing
  // Phase 4: Universal MCP and Team System Prompt
  // Phase 5: Load Memory and Inject into Context
  // Phase 6: Main Streaming Loop
  // Phase 7: Universal Notifications
}

Agent routing:

// src/app/(study)/api/chat/route.ts

if (!analyst.kind) {
  // Plan Mode - intent clarification
  const config = await createPlanModeAgentConfig(agentContext);
  await executeBaseAgentRequest(agentContext, config, streamWriter);

} else if (analyst.kind === AnalystKind.productRnD) {
  // Product R&D Agent
  const config = await createProductRnDAgentConfig(agentContext);
  await executeBaseAgentRequest(agentContext, config, streamWriter);

} else {
  // Study Agent (comprehensive research, fast insights, testing, creative, etc.)
  const config = await createStudyAgentConfig(agentContext);
  await executeBaseAgentRequest(agentContext, config, streamWriter);
}

Each agent only needs to define configuration:

// src/app/(study)/agents/configs/studyAgentConfig.ts

export async function createStudyAgentConfig(params) {
  return {
    model: "claude-sonnet-4",
    systemPrompt: studySystem({ locale }),
    tools: buildStudyTools(params),  // ← Tools this agent needs

    specialHandlers: {
      // Custom tool control
      customPrepareStep: async ({ messages }) => {
        const toolUseCount = calculateToolUsage(messages);
        let activeTools = undefined;

        // After report generation, restrict available tools
        if ((toolUseCount[ToolName.generateReport] ?? 0) > 0) {
          activeTools = [
            ToolName.generateReport,
            ToolName.reasoningThinking,
            ToolName.toolCallError,
          ];
        }

        return { messages, activeTools };
      },

      // Custom post-processing
      customOnStepFinish: async (step) => {
        // After saving research intent, auto-generate title
        const saveAnalystTool = findTool(step, ToolName.saveAnalyst);
        if (saveAnalystTool) {
          await generateChatTitle(studyUserChatId);
        }
      },
    },
  };
}

Why This Design?

Reasoning-execution separation rationale:

Matches cognitive model
- Human decision-making: first figure out "what to do", then consider "how to do it"
- System 1 (intuition) vs System 2 (reasoning)
- Plan Mode = System 2, Study Agent = System 1
Single responsibility
- Plan Mode: focuses on intent understanding, doesn't need to know execution details
- Study Agent: focuses on research execution, doesn't need to handle clarification
- Each is simpler and easier to maintain
Messages as protocol
- Plan Mode's decisions → messages
- Study Agent reads intent from messages
- Loosely coupled without losing context

Unified executor rationale:

Extract, Don't Rebuild
- Extract common patterns from three similar implementations
- Not designing abstraction layer from scratch
Configuration over Inheritance
- Agent differences expressed through configuration
- No inheritance or polymorphism
Plugin-based Lifecycle
- customPrepareStep: dynamic tool control
- customOnStepFinish: custom post-processing
- Preserve extension points, don't hard-code all logic

Comparison with other approaches:

Approach	Pros	Cons	Why not chosen
Plan Mode + baseAgentRequest	Remove duplicate code, separate reasoning-execution	One more abstraction layer	✅ Our choice
Continue copy-pasting	Simple and direct	Tech debt accumulates, hard to maintain	Unsustainable long-term
Fully generic agent	Least code	Sacrifices specialization and control	Can't handle business differences
Microservices split	Independent deployment	Over-engineered, adds ops complexity	Unnecessary at current scale

Impact

Code complexity:

Deleted:
- studyAgentRequest.ts (493 lines)
- fastInsightAgentRequest.ts (416 lines)
- productRnDAgentRequest.ts (302 lines)
Total: -1,211 lines

Added:
+ baseAgentRequest.ts (577 lines)
+ planModeAgentConfig.ts (120 lines)
+ studyAgentConfig.ts (180 lines)
+ productRnDAgentConfig.ts (80 lines)
Total: +957 lines

Net reduction: -254 lines

But more importantly:

Cyclomatic Complexity: 12.3 → 6.7 (45% reduction)
Code duplication: 95% → 0%

Development efficiency:

Before:

Adding MCP integration:
1. Modify studyAgentRequest.ts
2. Modify fastInsightAgentRequest.ts
3. Modify productRnDAgentRequest.ts
4. Test three agents

Time: 2-3 days

After:

Adding MCP integration:
1. Modify baseAgentRequest.ts
2. All agents automatically gain new capability

Time: 2-3 hours

User experience:

Before:

User: "Want to understand young people's coffee preferences"
AI: "Which age group do you want to research?"
User: "18-25"
AI: "What method do you want to use?"
User: "Interviews I guess"
AI: "How many people?"
... (3-5 conversation rounds)

After:

User: "Want to understand young people's coffee preferences"
AI displays complete plan:
┌─────────────────────────────────────┐
│ 【Research Plan】                   │
│ Goal: Understand 18-25 coffee prefs │
│ Method: Group discussion (5-8 ppl)  │
│ Duration: ~40 minutes               │
│ Output: Consumer insights report    │
│                                     │
│ [Confirm Start] [Modify Plan]       │
└─────────────────────────────────────┘

Intent clarification: 3-5 conversation rounds → 1 confirmation

III. Step 3: Persistent Memory

v2.3.0 - 2026-01-08

Problem: AI "Amnesia"

With intent clarification and unified architecture, the research workflow was smooth. But long-term users reported a problem:

"Why does the AI ask me what industry I'm in every single time?"

The AI doesn't remember users. Every conversation feels like the first meeting:

"What industry are you in?"
"Which dimensions do you care about?"
"What's your research goal?"

Users feel the AI is "forgetful", the experience lacks personalization.

Root cause:

LLMs are stateless. Each conversation:

const result = await streamText({
  messages: currentConversation,  // ← Only current conversation
  // No context from historical conversations
});

Although we have historical conversations in the DB:

Cross-conversation info lost: Each research is an independent session
Important info buried: Key information in long conversations is hard to extract
No persistent memory: No long-term memory of "who the user is"

Solution: Two-Tier Memory Architecture

We need a persistent memory system. But how to design it?

Inspired by Anthropic's CLAUDE.md approach:

Simple Markdown files
User-viewable and editable
Fully loaded into context

We adopted a similar approach but added automatic update mechanisms.

Data Model

model Memory {
  id      Int  @id @default(autoincrement())
  userId  Int? // User-level memory
  teamId  Int? // Team-level memory
  version Int  // Version management

  // Two-tier architecture
  core    String @default("") @db.Text  // Core memory (Markdown)
  working Json   @default("[]")         // Working memory (JSON, to be consolidated)

  changeNotes String @db.Text  // Update notes

  @@unique([userId, version])
  @@index([userId, version(sort: Desc)])
}

Two-tier architecture:

Core Memory (core)

Markdown format, human-readable
Long-term stable user information
Example:

 # User Information
 - Industry: Consumer goods product manager
 - Focus: Young consumer preferences, emerging trends

 # Research Style
 - Prefers qualitative research (interviews, discussions)
 - Values authentic user voices over statistics

Working Memory (working)

JSON format, structured
New information to be consolidated
Example:

 [
   { "info": "User recently focused on coffee market", "source": "chat_123" },
   { "info": "Prefers group discussion method", "source": "chat_124" }
 ]

Automatic Update Mechanism

Two-stage update:

// src/app/(memory)/actions.ts

async function updateMemory({ userId, conversationContext }) {
  let memory = await loadLatestMemory(userId);

  // Step 1: Reorganize when threshold exceeded (Claude Sonnet 4.5)
  if (memory.core.length > 8000 || memory.working.length > 20) {
    memory = await reorganizeMemory(memory, conversationContext);
  }

  // Step 2: Extract new information (Claude Haiku 4.5)
  const newInfo = await extractMemoryUpdate(memory.core, conversationContext);

  if (newInfo) {
    // Step 3: Insert new information at specified location
    await insertMemoryInfo(memory, newInfo);
  }
}

Memory Update Agent (Haiku 4.5):

Extract new user information from conversations
Low cost (~$0.001/time)
Runs in background after each conversation

Memory Reorganize Agent (Sonnet 4.5):

Consolidate working memory into core memory
Remove redundancy, merge similar information
Slightly higher cost (~$0.02/time), but infrequently triggered

Integration into Conversation Flow

// src/app/(study)/agents/baseAgentRequest.ts

// Phase 5: Load Memory
const memory = await loadUserMemory(userId);

if (memory?.core) {
  // Inject at conversation start
  modelMessages = [
    {
      role: 'user',
      content: `<UserMemory>\n${memory.core}\n</UserMemory>`
    },
    ...modelMessages
  ];
}

// Phase 6: Streaming
const result = await streamText({
  messages: modelMessages,  // ← Includes user memory
  // ...
});

// Phase 7: Non-blocking memory update
waitUntil(
  updateMemory({ userId, conversationContext: messages })
);

Why This Design?

Why Markdown over Vector DB?

Context window is large enough
- Claude 3.5 Sonnet: 200K tokens
- User memory typically < 10K characters (~3K tokens)
- Full loading is simpler and more accurate than retrieval
Simple and transparent
- Markdown is user-readable and editable
- No embeddings, no vector search, no complex indexing
- Aligns with Anthropic's philosophy: user control
Avoid premature optimization
- Don't need real-time retrieval (low conversation frequency)
- Don't need precise matching (full text provides enough context)
- Start with simple solution, optimize when necessary

Comparison with mainstream approaches:

Approach	Storage	Control	Retrieval	atypica choice rationale
Anthropic (CLAUDE.md)	File-based	User-driven	Full loading	✅ Simple, transparent, effective with large context
OpenAI	Vector DB (speculated)	AI + user confirmation	Semantic retrieval	❌ Black box, weak user control
Mem0	Vector + Graph + KV	AI-driven	Hybrid retrieval	❌ Over-engineered, high maintenance cost
MemGPT	OS-inspired tiered	AI self-managed	Tiered retrieval	❌ Conceptually complex, utility unproven

We chose Anthropic's simple approach because:

Fits current scale (personal assistant, not enterprise knowledge base)
User controllable (transparent, editable)
As context windows grow, this approach becomes better

Impact

User experience:

Before:

First conversation:
User: "Want to do coffee research"
AI: "What industry are you in?"
User: "Consumer goods"
AI: "What dimensions do you care about?"
...

Second conversation (a week later):
User: "Want to do tea beverage research"
AI: "What industry are you in?"  # ← Asks again

After:

First conversation:
User: "Want to do coffee research"
AI: "What industry are you in?"
User: "Consumer goods product manager"
# AI remembers

Second conversation (a week later):
User: "Want to do tea beverage research"
AI: "Based on your background as a consumer goods PM, I suggest..."  # ← Remembers!

System cost:

Memory Update (per conversation):
- Model: Claude Haiku 4.5
- Tokens: ~5K
- Cost: ~$0.001

Memory Reorganize (every 20 conversations):
- Model: Claude Sonnet 4.5
- Tokens: ~15K
- Cost: ~$0.02

Average cost: ~$0.002/conversation

Response time:

Memory loading: +50ms (non-blocking)
Memory update: background, doesn't affect response

Low cost, fast response, completely acceptable.

IV. Architecture Comparison: Our Unique Choices

Now let's step back and see how atypica's architecture differs from mainstream AI Agent frameworks.

State Management: Messages vs Memory Classes

atypica	LangChain	Core Difference
Messages as source	ConversationBufferMemory	We believe conversation history is the best state
Generate studyLog on demand	Pre-compute summary	Avoid sync issues, traceable on failures
DB stores derived state	DB stores core state	Similar to Event Sourcing

Why different?

LangChain's design is influenced by traditional software, believing "state should be explicitly stored and managed."

We believe, for LLMs:

Conversation history = complete state
Derived state (studyLog) can be regenerated
Simpler, more fault-tolerant

Agent Architecture: Configuration vs Graph

atypica	LangGraph	Core Difference
Configuration-driven	Graph-driven	We use configuration to express differences, code for commonalities
Single executor	Node orchestration	Avoid over-abstraction, good enough is enough
Messages as protocol	Explicit node communication	Loosely coupled without losing context

Why different?

LangGraph pursues generality, using graph orchestration to express arbitrarily complex flows.

We believe, for our scenarios:

Configuration-driven is simpler: 99% of needs can be met with configuration
Single executor is sufficient: Don't need graph orchestration's flexibility
Simpler is more reliable: Fewer abstraction layers, easier to debug

Memory System: Markdown vs Vector DB

atypica	Mem0	Core Difference
Markdown files	Vector + Graph + KV	We choose simple and transparent over precise and complex
Full loading	Semantic retrieval	When context window is large enough, full text is better
User-editable	AI black box	User trust comes from transparency

Why different?

Mem0 pursues precise retrieval, using multiple databases in hybrid.

We believe, for personal assistants:

Simple solution is enough: User memory typically < 10K
Transparent beats precise: Users can view and edit memory
Gets better as context grows: At 1M tokens in the future, this approach will crush Vector DB

Core Philosophy Differences

atypica's choices:

Simple, transparent, controllable
Adapt to LLM characteristics (large context, non-determinism)
Start from real pain points, not pursuing architectural perfection

Mainstream frameworks' choices:

Precise, complex, automatic
Port traditional software engineering patterns
Pursue generality and flexibility

Who's right or wrong?

Neither is wrong. It's just:

Our scenario (personal research assistant) suits simple approaches better
As context windows grow, simple approaches become better
User trust comes from transparency, not AI magic

V. Quantitative Impact

Specific impact from three evolutions:

Code Complexity

Duplicate code:
Before: 1,211 lines (three agent wrappers)
After: 0 lines
Reduction: 100%

Total lines of code:
Before: 1,211 lines (duplicates) + others
After: 577 lines (base) + 380 lines (configs) = 957 lines
Net reduction: 254 lines (21%)

Cyclomatic Complexity (code complexity metric):
Before: avg 12.3
After: avg 6.7
Reduction: 45%

Development Efficiency

Task	Before	After	Improvement
Add new research method	12 files, 2-3 days	3 files, 2-3 hours	10x
Add new capability (MCP)	Modify 3 places, 1 day	Modify 1 place, 2 hours	4x
Fix bug	Change 3 agents	Change 1 base	3x

System Performance

Token consumption (with prompt cache):
- studyLog generation: ~2K tokens (~$0.002)
- Memory update: ~5K tokens (~$0.005)
- Average per conversation: +$0.007

Response time:
- Memory loading: +50ms (non-blocking)
- Plan Mode: +2s (one-time)
- studyLog generation: background, doesn't affect response

Cost and performance impact negligible.

User Experience

Intent clarification:
Before: average 3.2 conversation rounds
After: 1 plan display + 1 confirmation
Improvement: 3x efficiency

AI "memory":
Before: repetitive questions every conversation
After: auto-load user preferences
Improvement: personalized experience

Research startup time:
Before: ~5 minutes (multiple rounds of clarification)
After: ~1 minute (one-click confirm)
Improvement: 5x efficiency

VI. Lessons Learned

What did we learn from three evolutions?

What We Did Right

1. Incremental refactoring, not big bang

We didn't rewrite the entire system at once. Three evolutions, each step:

Delivers value independently
Maintains backward compatibility (keeping analyst.studySummary field)
Can be rolled back

This let us quickly validate ideas and reduce risk.

2. Start from real pain points

Don't pursue architectural perfection, instead:

Message-driven: because adding discussionChat was too complex
Unified execution: because duplicate code was too much
Persistent memory: because users reported AI forgetfulness

Let problems drive design, not design drive problems.

3. Embrace LLM characteristics

Don't treat LLMs as traditional software:

Don't hand-write state machines, let AI infer state from conversations
Leverage large context windows, rather than pursuing precise retrieval
Let AI generate studyLog, rather than hand-writing parsers

Adapt to LLM's capability boundaries, rather than fighting them.

Costs We Paid

1. Learning curve for abstraction layer

baseAgentRequest requires understanding to modify:

6 phases of execution flow
Timing of customPrepareStep and customOnStepFinish
Generic constraints and type inference

But: clear interfaces and documentation lowered the barrier.

2. Cost of on-demand generation

studyLog generation requires LLM call (~$0.002/time).

But:

Prompt cache reduces cost by 90%
Architectural benefits >> small cost
Acceptable

3. Limitations of simple solutions

Markdown memory isn't suitable for:

Large-scale knowledge bases (> 100K tokens)
Complex relational queries
Multi-dimensional retrieval

But:

Good enough for personal assistant scenarios
Can upgrade to Vector DB in the future
Solve 80% of problems first

Unexpected Benefits

1. Confidence from type safety

// Fully type-safe tool handling
const tool = step.toolResults.find(
  t => !t.dynamic && t.toolName === ToolName.generateReport
) as StaticToolResult<Pick<StudyToolSet, ToolName.generateReport>>;

if (tool?.output) {
  const token = tool.output.reportToken;  // ← TypeScript knows this field exists
}

During refactoring, the compiler catches 99% of issues.

2. Flexibility of configuration-driven

Adding webhook integration only requires:

// baseAgentRequest.ts
if (webhookUrl) {
  await sendWebhook(webhookUrl, step);
}

All agents automatically gain new capability, no config changes needed.

3. Power of messages as protocol

Plan Mode and Study Agent communicate through messages:

Decoupled: can be modified independently
Without losing context: complete decision process in messages
Traceable: can replay when problems occur

This was an unexpected benefit.

VII. Future Directions

Three evolutions brought atypica closer to general-purpose agents. But there's more to do.

Short-term (3-6 months)

1. Skills Library

Further modularize tools
Users can compose their own agents
Like GPTs, but more flexible

2. Multi-Agent Collaboration

Not just serial execution
Parallel research, cross-validation
Like AutoGPT, but more controllable

Long-term (1-2 years)

3. Evolve toward GEA

GEA = General Execution Architecture
Not just research agents, but a universal AI Agent execution framework
Can run any type of agent

4. Self-Improving Agents

Agents learn from past executions
Continuously optimize prompts and strategies
Get smarter with use

Unchanging Principles

No matter how we evolve, we stick to:

Simple beats complex
Transparent beats black box
User control beats AI automation

VIII. Conclusion

Building AI Agent systems is not a simple extension of traditional software engineering.

We need to rethink:

What is state? (Conversation history)
What is an interface? (Message protocol)
What is control flow? (AI reasoning)

atypica's three evolutions are essentially three cognitive upgrades:

From database thinking → data flow thinking
- Don't maintain explicit state, infer state from messages
From code reuse → configuration-driven
- Don't pursue perfect abstraction, use configuration to express differences
From stateless → memory-enhanced
- Don't rely on precise retrieval, use simple and transparent methods

These choices may not be the most "advanced."

But they are:

Simple: easy to understand, easy to debug
Transparent: users know what AI is doing
Controllable: users can intervene and adjust
Good enough: solve 80% of problems

And this, perhaps, is the key to building reliable AI systems.

https://atypica.ai/blog/towards-general-agent

Designing Natural AI Memory: Why It Feels Awkward and How to Fix It

web3nomad.eth — Sun, 11 Jan 2026 09:41:34 +0000

You've built memory into your AI. Users can now have conversations that reference past interactions. Great!

Except... users feel weird about it.

The Problem

Here's what usually happens:

User: "Help me research Gen-Z skincare trends"

AI: (researches, provides insights)

User: (two weeks later) "Now help me with Gen-Z gaming behavior"

AI: "According to your saved preferences from our conversation on March 5th at 2:34 PM, you prefer detailed analysis with customer insights. I also notice from your previous research on March 5th that you focus on Gen-Z demographics. Based on these stored memories..."

User: 😬

That AI just turned helpful into awkward in one response.

What Users Actually Want

Same scenario, different approach:

User: (two weeks later) "Now help me with Gen-Z gaming behavior"

AI: "Interesting—continuing that Olay campaign logic from last time where emotional connection beat price sensitivity. Gaming probably works the same way. Let me look..."

User: 😊

See the difference? The second AI understood without announcing it understood. It referenced a specific past project naturally, like a colleague would.

The Big Insight

Users don't want AI that "remembers." They want AI that gets them.

Even better: AI that knows what they need before they do.

Think about your best friend. They don't say "I remember you telling me on Tuesday you like coffee." They just show up with coffee.

And sometimes, they show up with coffee when you didn't even realize you needed one.

That's the experience you're building toward.

How to Get There

1. Stop Making AI Sound Like a Database

Bad:

"Your stored preference indicates..."
"According to our conversation history..."
"I remember you mentioned..."
"Based on your saved settings..."

Good:

"Continuing that Olay campaign logic..."
"Like you found last time with skincare..."
"You usually want the detailed version, so..."
Just do it without saying anything

The pattern: Reference naturally or stay quiet. Never announce the fact that you're referencing memory.

2. Make Preferences Actually Do Something

I see this constantly:

User: "I prefer detailed analysis"
[AI stores it]
*Next conversation*
AI: "Would you like a brief or detailed analysis?"

If you're storing preferences but not using them, you're just building a surveillance system with extra steps.

Fix it: When AI knows user wants detailed analysis, just output detailed analysis. Skip the question. That's what memory is FOR.

3. Proactively Connect the Dots

This is where good memory becomes indispensable:

User: "Help me with Gen-Z beauty trends"

AI: "You researched skincare three months ago and found emotional authenticity mattered more than price. That Z-gen insight probably applies here too—want me to focus on emotional drivers?"

See what happened? AI didn't wait for the user to connect the dots. It:

Recalled a relevant past research
Identified the pattern (Gen-Z consumer behavior)
Offered to apply the insight proactively

Another example:

User: "I need campaign ideas for a new product launch"

AI: "Last time with the PH launch you said you wanted to try AI-generated video. Runway just released their new model—should I include some video concepts?"

The AI remembered an unexplored interest and brought it up at the perfect moment.

This is what "understanding you better than you understand yourself" looks like in practice.

4. Don't Store Everything—Store Signposts

Here's a mistake I see everywhere:

Memory Database:
- March 5: User researched Gen-Z skincare. Found emotional triggers
  important. Interviewed 8 personas. Key insight was that authentic
  brand voice matters more than celebrity endorsements. Focused on
  Instagram and TikTok as primary channels. Budget was $50k. Client
  was Olay. Campaign theme was "Real Beauty Real Talk"...
- April 2: User researched Gen-Z gaming. Found community matters.
  Interviewed 5 personas. Discord important. Twitch streamers...
- May 1: User researched Gen-Z fashion...
[... 500 more entries like this]

Your database just exploded. Worse, AI can't find patterns because it's drowning in details.

Better:

Memory:
- Research history: Skincare Gen-Z/Olay (emotions > price), Gaming Gen-Z
  (community matters), Fashion Gen-Z (sustainability key)
- Pattern: Always asks about Gen-Z consumer behavior
- Unexplored interests: Mentioned wanting to try AI video generation

One-line summaries with just enough detail to trigger recall. That's it. The full research already lives in your database—memory should just help AI connect dots across conversations.

5. Make Memory Tangible

Users trust memory more when they can see it:

Timeline view:

You and I have worked together for 6 months
↓
5 research projects completed
↓
3 recurring themes identified
↓
Your campaigns now start 40% faster

Milestone moments:

AI: "We've been working together for a year now—from that first positioning
discussion for Olay to today's Gen-Z gaming research. Want to see how your
research focus has evolved?"

Knowledge graph:
Show what AI remembers and how pieces connect. Like Notion's "Mentioned in" feature, but for your brain.

This isn't just nice-to-have. Visible memory builds trust. Users understand what AI knows and what it doesn't.

6. Let Understanding Grow Over Time

Here's what instant omniscience looks like:

User: (first conversation ever)
AI: "I've analyzed your communication patterns and determined you prefer structured analysis with executive summaries. I've also noted your focus on actionable insights over theoretical frameworks..."

User: "...we literally just met?"

Feels like AI is pretending to know you when it doesn't.

Better experience:

1st time: User explains everything. AI takes notes.

3rd time: AI starts anticipating. "Should I include user interviews like last time?"

10th time: AI challenges. "You usually care about Gen-Z, but this product is really for Millennials. Sure you want Gen-Z angle?"

1 year anniversary: "We've done 12 projects together. You've shifted from purely tactical campaigns to strategic positioning. Want me to default to strategic framing now?"

That progression from helper → anticipator → thought partner → strategic advisor feels natural. Instant expertise feels fake.

The Three Ways to Kill Your Memory Feature

1. Say "I Remember" Too Much

Every AI builder tries this at some point:

"I remember you like detailed analysis. I remember you focus on Gen-Z. I remember you prefer interviews over surveys. I remember..."

Users feel watched. Like AI is showing off that it's tracking them.

Fix: Reference naturally when it adds value. Otherwise shut up about it.

2. Never Use What You Stored

The opposite problem:

AI accumulates thousands of memory entries... and never references any of them. Users wonder why you asked for all that information.

Fix: If a stored fact doesn't change AI behavior, delete it. Every memory item must earn its keep.

3. Update at the Wrong Time

Tempting: Update memory after every single message.

Reality: Most conversation is exploration. Users trying things out. Not worth storing.

Better: Update at natural completion points:

Finished a research project? Update.
Solved a problem? Update.
Completed a document? Update.
Hit a milestone? Update.

You get complete context, stable information, and clearer patterns. Plus it's way cheaper.

The Moment You're Building Toward

You've succeeded when a user has this experience:

They ask for something. AI does exactly what they wanted, exactly how they wanted it.

Better yet: AI suggests something they didn't even know they wanted.

User pauses.

"Wait... this AI actually gets me."

That moment doesn't come from AI announcing "I remember your preferences."

It comes from AI doing the right thing before being asked.

It comes from AI saying "You researched skincare three months ago—that insight might help here."

It comes from AI connecting dots the user didn't even see yet.

The Test

Next time you're about to make AI say "I remember..." or "based on your stored preferences...", try this instead:

Just do what the memory says to do. Don't announce it.

Or better: Proactively connect it to something the user is working on now.

If the user notices and appreciates it—you nailed it.

If the user doesn't notice—even better. That's memory working perfectly. Invisible until that one moment when it clicks.

If the user says "how did you know?"—you've transcended. That's when memory becomes magic.

Good memory feels like understanding, not surveillance.

Great memory feels like mind-reading.

https://atypica.ai/blog/designing-natural-ai-memory