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

Source: Dev.to

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:

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

Your agent doesn’t remember architecture decisions, bugs you fixed together, or 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 – loads previous context
n2_boot(agent, project)

// Session end – saves everything
n2_work_end(agent, project)

That’s it. On the next session, the agent boots up and knows everything from the last time — what it worked on, what decisions were made, and what’s left to do.

Real‑World Example

I run a multi‑agent team. Here’s a typical handoff:

Agent A (Gemini Pro) ends a 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"]
})

Agent B (Claude) starts a new session

n2_boot({ "agent": "antigravity", "project": "MyProject" })

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 uses progressive loading to adjust detail level based on your token budget:

Immutable Ledger

Every work session is recorded as an append‑only JSON log, giving you a complete history of what each 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',
    },
  },
};

Quick Start

git clone https://github.com/choihyunsus/soul.git
cd soul
npm install

Add to your MCP config:

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

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.

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:
• 🌐 Website:
• 📄 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. 🤖