soul.py is a Python library that provides persistent memory for local LLM sessions by storing conversation history in human-readable markdown files, eliminating the need for databases or running servers.

How it works

The library creates two markdown files: SOUL.md for identity information and MEMORY.md for conversation logs. Every time you call agent.ask(), the system reads both files into the system prompt, processes the query, then appends the exchange to MEMORY.md. This allows memory to survive across processes and sessions.

Basic usage

Installation and setup:

pip install soul-agent
soul init

Example implementation with Ollama:

from soul import Agent

agent = Agent(
    provider="openai-compatible",
    base_url="http://localhost:11434/v1",
    model="llama3.2",
    api_key="ollama"
)
agent.ask("My name is Prahlad, I'm working on an AI research lab.")
Later, in a new session:
agent.ask("What do you know about me?")
Returns: "You're Prahlad, working on an AI research lab."

Key features

• Works with Ollama, OpenAI, and Anthropic models
• No database or server required
• Human-readable markdown files
• Git-versionable and editable by hand
• Memory persists across processes and sessions
• Built specifically for adding persistent memory to local models

The tool was created to solve the problem of local LLMs forgetting information between sessions, providing a lightweight alternative to database-backed solutions.