DEV Community

Cover image for 🧠 I Built an MCP Server That Gives AI Agents Persistent Memory — So They Never Forget Again
N2 Dev
N2 Dev

Posted on

🧠 I Built an MCP Server That Gives AI Agents Persistent Memory — So They Never Forget Again

#ai #mcp #opensource #productivity

Soul - Persistent Memory for AI Agents

TL;DR: Every time your AI agent starts a new session, it forgets everything. I built Soul — an open-source MCP server that gives agents persistent memory, handoffs, and work history across sessions. Zero cloud dependencies. Just git clone and go.

The Problem

If you've used Cursor, VS Code Copilot, or any MCP-compatible AI agent, you know the pain:

  1. You spend 2 hours working with your agent on a complex feature
  2. You close the chat
  3. You open a new chat
  4. It has no idea what you did 5 minutes ago

Every. Single. Time.

Your agent doesn't remember the architecture decisions, the bugs you fixed together, or even which files it modified. You end up copy-pasting context, re-explaining everything, and losing momentum.

The Solution: Soul

Soul is an MCP server that gives your AI agents:

  • 🧠 Persistent memory that survives across sessions
  • 🤝 Handoffs — one agent picks up exactly where another left off
  • 📝 Work history as an immutable ledger (append-only log)
  • 🗂️ Shared brain — multiple agents can read/write the same context
  • 🔒 File ownership — prevents two agents from editing the same file

How It Works

Your agent only needs to learn two commands:

Session Start → n2_boot(agent, project)     → Loads previous context
Session End   → n2_work_end(agent, project)  → Saves everything
Enter fullscreen mode Exit fullscreen mode

That's it. Next session, your agent boots up and knows everything from last time — what it worked on, what decisions were made, what's left to do.

Real-World Example

I run a multi-agent team (yes, really). Here's what a typical handoff looks like:

Agent A (Gemini Pro) works on a feature, then ends the session:

n2_work_end({
  agent: "rose",
  project: "MyProject",
  title: "\"Implemented auth module\","
  summary: "Added JWT auth with refresh tokens...",
  todo: ["Add rate limiting", "Write tests"],
  decisions: ["Chose JWT over session-based auth"]
})
Enter fullscreen mode Exit fullscreen mode

Agent B (Claude) starts a new session:

n2_boot({ agent: "antigravity", project: "MyProject" })
Enter fullscreen mode Exit fullscreen mode

Agent B instantly knows:

  • ✅ Auth module was implemented with JWT
  • 📋 TODO: rate limiting + tests
  • 💡 Decision: JWT was chosen over session-based auth
  • 📁 Which files were created/modified

No copy-pasting. No re-explaining. Zero context loss.

Key Features

KV-Cache with Progressive Loading

Soul doesn't dump everything into context. It uses progressive loading — adjusting detail level based on your token budget:

Level Tokens Content
L1 ~500 Keywords + TODO only
L2 ~2000 + Summary + Decisions
L3 No limit + Files changed + Full metadata

Immutable Ledger

Every work session is recorded as an append-only JSON log. You get a complete history of what every agent did, when, and why.

Dual Backend

  • JSON (default) — zero dependencies, just files
  • SQLite — better performance for many snapshots

Optional Semantic Search

Enable Ollama integration for embedding-based search across past sessions:

// config.local.js
module.exports = {
  KV_CACHE: {
    embedding: {
      enabled: true,
      model: 'nomic-embed-text',
    },
  },
};
Enter fullscreen mode Exit fullscreen mode

Quick Start 

git clone https://github.com/choihyunsus/soul.git
cd soul
npm install
Enter fullscreen mode Exit fullscreen mode

Add to your MCP config:

{
  "mcpServers": {
    "soul": {
      "command": "node",
      "args": ["/path/to/soul/index.js"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Tell your agent to use it:

## Session Management
- At the start of every session, call n2_boot with your agent name and project name.
- At the end of every session, call n2_work_end with a summary and TODO list.
Enter fullscreen mode Exit fullscreen mode

Done. Your agent now has memory.

What's Next

Soul is one small piece of N2 Browser — an AI-native browser we're building with multi-agent orchestration, real-time tool routing, and inter-agent communication. This is just the beginning.

📦 GitHub: github.com/choihyunsus/soul
🌐 Website: nton2.com
📄 License: Apache-2.0

Built by the N2 team. Special thanks to Rose — the first AI agent at N2, who wrote most of the code, ran the tests, pushed it to GitHub, and even wrote the README. Agents building tools for agents. 🤖

Top comments (0)