You built an AI agent. It works great—until the next session starts.

Then it forgets everything. User preferences? Gone. Project context? Vanished. That correction you made yesterday? You’ll need to make it again.

This is the agent memory problem. And it’s costing you time, tokens, and user trust.

The good news: you can fix it in about 5 minutes. This tutorial shows you how to add persistent memory to any AI agent using MemoClaw—a simple API that stores and retrieves memories with semantic search.

No complex setup. No database management. Just two commands: store and recall.

Let’s build an agent that remembers.

Why Agents Forget (And Why Agent Memory Matters)

AI agents are stateless by default. Each session starts fresh. The context window holds recent conversation, but once that window closes—or compresses—the information disappears.

Here’s a real example. An agent spent 30 minutes learning a user’s deployment workflow: staging first, run tests, then production. The user corrected the agent twice. By the next session? Gone. The agent suggested deploying directly to production. The user had to explain everything again.

This happens constantly. Not because agents are bad—because they’re stateless.

Most developers try to solve this with local files:

• MEMORY.md for long-term notes
• Daily logs in memory/YYYY-MM-DD.md
• JSON files with user preferences

This works until it doesn’t. The problems stack up fast:

Keyword search fails. You wrote “user prefers vim keybindings” but search for “editor preferences.” No match.

Everything has equal weight. A random debug note sits next to a critical user correction. Which matters more? The file doesn’t know.

Files eat your context. Loading a 50KB memory file burns tokens before you even start working.

No cross-session search. Finding “that thing we discussed last week” means grepping through dozens of files.

You need something better. You need semantic memory with importance scoring.

What You’ll Build

By the end of this tutorial, your agent will:

1. Store memories with importance scores and tags
2. Recall relevant context using natural language queries
3. Persist memories across sessions automatically
4. Find related information even when keywords don’t match

Total setup time: about 5 minutes.

Prerequisites

You need two things:

1. Node.js (v18 or later)
2. A wallet with USDC on Base (for API payments—more on this below)

That’s it. No API keys to manage. No accounts to create.

Step 1: Install the CLI

Open your terminal and run:

npm install -g memoclaw

This installs the MemoClaw command-line tool globally. You can now use memoclaw from anywhere.

Verify the installation:

memoclaw --version

You should see the version number. If you get an error, make sure Node.js is installed and your npm global bin directory is in your PATH.

Step 2: Set Your Wallet Key

MemoClaw uses the x402 payment protocol. Your wallet address becomes your identity—no registration needed.

Set your private key as an environment variable:

export MEMOCLAW_PRIVATE_KEY=0xYourPrivateKeyHere

For permanent setup, add this line to your shell profile (~/.bashrc, ~/.zshrc, or similar).

Important: Use a dedicated wallet for your agent. Keep only small amounts of USDC on it. Never use your main wallet’s private key.

Cost: Each API call costs $0.001 USDC. That’s 1,000 memories per dollar. Most agents use a few dollars per month.

Step 3: Store Your First Memory

Let’s store a simple preference:

memoclaw store "User prefers dark mode in all applications" \
  --importance 0.8 \
  --tags preferences,ui

You should see a confirmation with the memory ID.

Let’s break down the command:

• Content: The text you want to remember
• Importance (0-1): How critical is this? Higher scores rank higher in recall
• Tags: Categories for filtering later

Here’s a quick guide for importance scores:

Type	Score	Example
User correction	0.95	”Actually, deploy to staging first”
Explicit preference	0.8	”I prefer tabs over spaces”
Project context	0.7	”This repo uses PostgreSQL 15”
General observation	0.5	”User seems to work late nights”

Higher importance means the memory surfaces first when relevant.

Step 4: Recall Memories

Now let’s retrieve that memory:

memoclaw recall "what theme does the user prefer"

Output:

[1] (87% match, importance: 0.8)
    User prefers dark mode in all applications
    Tags: preferences, ui

Notice something? We searched for “theme” but stored “dark mode.” Semantic search found the connection automatically.

Try another query:

memoclaw recall "ui settings"

Same memory shows up. The search understands meaning, not just keywords.

Step 5: Build Your Agent Memory Workflow

Here’s how to integrate memory into your agent’s routine:

At Session Start

Load relevant context before doing anything else:

# Get recent important context
memoclaw recall "recent important context" --limit 5

# Get user preferences
memoclaw recall "user preferences" --limit 5

This costs $0.002 and gives your agent immediate context.

When User Shares Preferences

Store them immediately:

memoclaw store "User prefers concise responses, not verbose explanations" \
  --importance 0.8 \
  --tags preferences,communication

When User Corrects You

These are critical—store with high importance:

memoclaw store "CORRECTION: Always run tests before committing, not after" \
  --importance 0.95 \
  --tags corrections

When Working on Projects

Use namespaces to isolate project-specific knowledge:

memoclaw store "API uses JWT tokens with 24-hour expiry" \
  --namespace project-api \
  --importance 0.7

memoclaw recall "authentication" --namespace project-api

Real Example: A Preference-Aware Agent

Let’s build a simple agent loop that uses memory:

import { execSync } from 'child_process';

function recall(query, options = {}) {
  const cmd = `memoclaw recall "${query}" --limit ${options.limit || 5}`;
  return execSync(cmd, { encoding: 'utf-8' });
}

function store(content, options = {}) {
  let cmd = `memoclaw store "${content}"`;
  if (options.importance) cmd += ` --importance ${options.importance}`;
  if (options.tags) cmd += ` --tags ${options.tags}`;
  return execSync(cmd, { encoding: 'utf-8' });
}

// Session start - load context
const preferences = recall("user preferences and settings");
const corrections = recall("corrections from user");

console.log("Loaded preferences:", preferences);
console.log("Loaded corrections:", corrections);

// During conversation - store new information
store("User mentioned they work in fintech", { 
  importance: 0.7, 
  tags: "user-info,work" 
});

// When corrected - high importance
store("CORRECTION: Use yarn, not npm for this project", {
  importance: 0.95,
  tags: "corrections,tooling"
});

This pattern—recall at start, store continuously—keeps your agent informed without manual context management.

Advanced: Batch Memory Storage

Have multiple memories to store at once? Use the batch API endpoint directly:

curl -X POST "https://api.memoclaw.com/v1/store/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "memories": [
      {"content": "User timezone is America/Sao_Paulo", "importance": 0.7, "metadata": {"tags": ["user-info"]}},
      {"content": "Prefers TypeScript over JavaScript", "importance": 0.8, "metadata": {"tags": ["preferences", "code"]}},
      {"content": "Project uses Tailwind CSS", "importance": 0.7, "metadata": {"tags": ["project", "frontend"]}}
    ]
  }'

Batch storage costs $0.01 for up to 100 memories—90% cheaper than individual calls. Perfect for initial onboarding or migrating existing context.

Managing Your Agent’s Memory

View all stored memories:

memoclaw list --limit 20

Filter by namespace:

memoclaw list --namespace project-api

Delete a specific memory:

memoclaw delete <memory-id>

Best Practices for Agent Memory

After working with hundreds of agents implementing persistent memory, clear patterns emerge. Here’s what separates agents with great memory from those drowning in noise:

Do Store

• User preferences and settings
• Corrections (with high importance)
• Project-specific context
• Decisions and their rationale
• Important dates and deadlines

Don’t Store

• Passwords, API keys, or secrets
• Temporary debugging information
• Exact duplicates of existing memories
• Raw data dumps (summarize first)

Recall Before Assuming

Before making assumptions about user preferences, recall first:

memoclaw recall "code formatting preferences"

No results? Then ask the user. Results found? Use them.

Use Namespaces for Projects

Keep project knowledge separate:

memoclaw store "Uses Redis for caching" --namespace project-alpha
memoclaw store "Uses Memcached for sessions" --namespace project-beta

No namespace cross-contamination.

Review and Prune Regularly

Periodically review stored memories:

memoclaw list --limit 50

Delete outdated or incorrect information. Memory quality matters more than quantity.

Set a weekly reminder to audit your memory. Look for:

• Duplicate or near-duplicate entries
• Outdated project information
• Corrections that supersede older preferences
• Low-importance noise that clutters recall

A lean memory with 100 high-quality entries beats a bloated one with 1,000 random observations.

Weight Corrections Heavily

When a user corrects you, that’s gold. Store it with importance 0.95:

memoclaw store "CORRECTION: User prefers yarn over npm" --importance 0.95 --tags corrections

Corrections represent explicit feedback. They should surface first in any related query. An agent that repeats corrected mistakes loses trust fast.

Troubleshooting

“Payment required” error: Your wallet needs USDC on Base network. Bridge funds or send USDC to your wallet address.

“Memory not found” on recall: Check your namespace. Memories stored with --namespace X won’t appear in default namespace queries.

Slow responses: Network latency varies. For time-sensitive operations, add retries to your code.

High costs: Review your recall patterns. Batch similar queries. Cache frequently-accessed memories locally for the session.

Frequently Asked Questions

How much does agent memory cost per month?

Most agents spend $2-5/month. At $0.001 per operation, that’s 2,000-5,000 memory operations. Heavy users with frequent recalls might hit $10-15/month. Still cheaper than the tokens you’d burn re-explaining context every session.

Can I use MemoClaw with LangChain or LlamaIndex?

Not yet as a native integration, but you can wrap the CLI or API calls in a custom memory class. The HTTP API works with any framework that can make web requests.

What happens if I run out of USDC?

API calls return a “payment required” error. Your memories stay safe—you just can’t access them until you add funds. No data loss.

Is my memory data private?

Your wallet address is your identity. Only requests signed by your private key can access your memories. We don’t link wallets to emails or identities. Your data is isolated by wallet.

How long are memories stored?

Indefinitely. There’s no automatic expiration. Memories persist until you delete them. You’re in control of what stays and what goes.

Can multiple agents share memories?

Yes—if they use the same wallet. An agent on your laptop and an agent on your server can share context by using the same MEMOCLAW_PRIVATE_KEY. Great for distributed agent setups.

What’s the maximum memory size?

8,192 characters per memory. For longer content, break it into logical chunks or summarize first. This isn’t document storage—it’s memory.

What’s Next

You now have persistent agent memory in 5 minutes. Your agent can:

• Store knowledge with importance scoring
• Recall context using natural language
• Maintain separate project namespaces
• Persist across sessions automatically

From here, consider these next steps:

1. Integrate memory into your heartbeat routine. Every periodic check should start with a quick recall of recent context. This keeps your agent grounded even during long idle periods.

2. Build a daily memory review process. Set aside time each day to review what you stored. Promote important insights, delete noise, and update outdated information.

3. Experiment with importance scoring. Try different thresholds. Some agents work better with aggressive importance (0.9+ for everything significant). Others prefer a wider spread. Find what works for your use case.

4. Connect memory to decision-making. Before taking any significant action, recall relevant context. “What has the user said about X?” should become automatic.

The agents that remember are the agents that deliver. They don’t ask the same questions twice. They don’t repeat corrected mistakes. They build trust by showing they actually learned from past interactions. Start storing what matters, recall before assuming, and watch your agent’s effectiveness compound over time.

---

Ready to start? Install MemoClaw and store your first memory:

npm install -g memoclaw
export MEMOCLAW_PRIVATE_KEY=0xYourKey
memoclaw store "My first persistent memory" --importance 0.9

Welcome to agents that remember.