soul.py is a 150-line Python library that gives any LLM persistent memory and identity using plain markdown files. No database or vector store required.

How do I install soul.py?

Install with pip install soul-agent, then run soul init to create your SOUL.md and MEMORY.md files.

How does soul.py store memories?

soul.py uses two markdown files: SOUL.md for agent identity and MEMORY.md for timestamped conversation logs. Every exchange is appended automatically.

Does soul.py require a database?

No. soul.py uses plain markdown files for storage. No database, no vector store, no infrastructure needed.

What LLM providers does soul.py support?

soul.py supports Anthropic, OpenAI, and any OpenAI-compatible API including local models via Ollama.

How is soul.py different from LangChain or MemGPT?

soul.py is a minimal primitive (150 lines), not a framework. It adds persistent memory without requiring you to adopt an entire agent architecture.

Will soul.py work with local LLMs?

Yes. Configure soul.py with provider openai-compatible and point base_url to your local Ollama or other OpenAI-compatible server.

What happens when MEMORY.md gets too large?

For v0.1, large memory files may overflow context. Version 2.0 adds RAG retrieval to handle unlimited memory with semantic search.

soul.py: Your AI Remembers Nothing. This Fixes It in 10 Lines.

By Prahlad Menon Published 2026-03-01 2 min read

📚 The Book is Here! Everything in this post (and much more) is now in Soul: Building AI Agents That Remember Who They Are — Available on Amazon →

🆕 v0.2.0 — Modulizer: Large MEMORY.md files burn tokens. The new Modulizer splits them into indexed modules for 40-60% token savings. Zero infrastructure needed. Read the writeup →

Every AI conversation starts the same way: “Hi, I’m Claude/GPT/Llama, how can I help you today?”

You’ve talked to this model a hundred times. You’ve told it your name, your projects, your preferences. It doesn’t matter. The moment the session ends, it forgets everything. Tomorrow, you start from zero.

This is the most basic failure mode in AI agents, and somehow we’ve normalized it.

The 10-Line Fix

from soul import Agent

agent = Agent()
agent.ask("My name is Prahlad and I'm building an AI research lab.")
# → "That's exciting — what are you working on first?"

# Later. New process. New session. Memory persists.
agent = Agent()
agent.ask("What do you know about me?")
# → "You're Prahlad, building an AI research lab."

That’s soul.py. Memory survives across processes—no database, no server, nothing running in the background.

How It Actually Works

soul.py uses two markdown files as the agent’s persistent state:

File	Purpose
`SOUL.md`	Identity — who the agent is, how it behaves
`MEMORY.md`	Memory — timestamped log of past exchanges

Every agent.ask() call:

Reads SOUL.md + MEMORY.md into the system prompt
Calls the LLM
Appends the exchange to MEMORY.md with a timestamp

That’s the entire architecture. 150 lines of Python.

What MEMORY.md Looks Like

After a few conversations:

# MEMORY.md

## 2026-03-01 08:00
Q: My name is Prahlad and I'm building an AI research lab.
A: That's exciting — what are you working on first?

## 2026-03-01 09:15
Q: What should I focus on today?
A: Based on your AI lab work, you mentioned the memory paper 
   was the priority...

Human-readable. Version-controllable. Editable by hand. git diff your agent’s memories if you want.

The Setup

pip install soul-agent

soul init

The wizard asks two questions:

What’s your agent’s name?
Which provider? (anthropic / openai / openai-compatible)

Creates SOUL.md and MEMORY.md in your current directory. You’re done.

Works With Everything

# Anthropic (default)
agent = Agent(provider="anthropic")

# OpenAI
agent = Agent(provider="openai")

# Local Ollama — no API key needed
agent = Agent(
    provider="openai-compatible",
    base_url="http://localhost:11434/v1",
    model="llama3.2",
    api_key="ollama"
)

Why Not LangChain / MemGPT / Clawdbot?

Those are frameworks. soul.py is a primitive.

LangChain — orchestration layer, requires significant setup
LlamaIndex — document indexing, needs vector store infrastructure
MemGPT — impressive but opinionated about the full agent stack
Clawdbot / OpenClaw — full agent runtime with tools, channels, scheduling, approval gates

The last category is worth expanding on. Tools like Clawdbot give you a complete agent infrastructure: Telegram/Discord/Slack integration, browser automation, cron jobs, exec sandboxing, the works. If you’re building a production agent that needs to do things in the world, that’s the right choice.

But what if you just want your Python script to remember who it’s talking to?

soul.py is the answer when:

You’re building something custom and don’t want a framework
You want memory without buying into an entire agent architecture
You need to drop persistent identity into an existing codebase
You want files you can read, edit, and git diff

It’s the difference between “I need a car” and “I need wheels.” Sometimes you just need wheels.

What v0.1 Doesn’t Do (Yet)

Once MEMORY.md gets very large (thousands of entries), it’ll overflow the context window. That’s the v2.0 problem — solved with RAG retrieval.

For most use cases, v0.1 runs indefinitely. A typical daily exchange is ~200 words. You’d hit the context limit after roughly 6 months of daily use. Plenty of runway.

The versions:

v0.1: Markdown-native, zero infrastructure
v2.0: RAG + RLM hybrid with query routing (uses Qdrant + Azure embeddings)

Try v2.0: soulv2.themenonlab.com

The Philosophy

The best infrastructure is no infrastructure.

Vector databases are powerful. They’re also another service to run, another thing to break, another dependency to manage. For most agent use cases—personal assistants, research companions, project copilots—you don’t need them. You need a text file that persists.

soul.py starts there. When you outgrow it, the upgrade path exists. But most people won’t need it for months.

Try It Now — No Install Required

Live demo: soul.themenonlab.com

Chat with a soul.py agent and watch MEMORY.md fill up in real time. Ask it something, then try “What do you know about me so far?” — you’ll see exactly how the memory injection works under the hood.

No API key needed. No signup. Just try it.

(Demo source is also open: soul.py-demo — ~150 lines of FastAPI if you want to self-host)

Get Started Locally

pip install soul-agent
soul init

Star the repo: github.com/menonpg/soul.py

Your AI shouldn’t have amnesia. Fix it in 10 lines.

Community Response

Within hours of sharing soul.py on Reddit, it became the #1 post of all time on r/ollama — a community of 100K+ developers running local LLMs.

The numbers (first 9 hours):

📈 24,000+ views
🏆 #1 post on r/ollama
🌍 Readers from 50+ countries (37% US, 7% Germany, 5% Canada)
💬 Dozens of questions and feature discussions

soul.py — Persistent memory for any LLM in 10 lines (works with Ollama, no database)
by u/the_ai_scientist in r/ollama

The response validated something we suspected: developers want memory without complexity. Not every project needs a vector database. Sometimes you just need a text file that persists.

Thanks to everyone who tried it, asked questions, and pushed us to add v2.0’s RAG support. This is just the beginning.

The Book

Everything in this post — and much more — is now in “Soul: Building AI Agents That Remember Who They Are”.

The book covers:

Why agents forget (architectural deep dive)
Identity vs Memory (SOUL.md vs MEMORY.md philosophy)
The RLM Pattern (when RAG isn’t enough)
Multi-agent identity coordination
The Darwinian approach to evolving agent identity
Complete working code in every chapter

→ Get “Soul” on Amazon | → Gumroad Bundle (PDF + setup wizard + cheatsheets)

Try the live demo: Ask Darwin — an AI companion built with the same architecture the book teaches.