langchain-soul 0.1.0

Markdown-native memory for LangChain. Human-readable, git-versionable, powered by soul-agent.

langchain-soul 🧠

Markdown-native memory for LangChain.

Your conversation history shouldn't be a black box. langchain-soul stores everything in human-readable markdown files:

• SOUL.md — Agent identity
• MEMORY.md — Timestamped conversation log

Human-readable. Git-versionable. Powered by soul-agent.

Install

pip install langchain-soul

Quick Start

from langchain_soul import SoulMemory
from langchain.chains import ConversationChain
from langchain_openai import ChatOpenAI

# Create markdown-based memory
memory = SoulMemory()

# Use with LangChain
chain = ConversationChain(llm=ChatOpenAI(), memory=memory)

response = chain.predict(input="Hello! How are you?")
print(response)

response = chain.predict(input="What did I just say?")
print(response)  # Remembers the conversation!

After running, check MEMORY.md:

# Conversation History

## 2026-03-06 19:20:15 UTC
**Human:** Hello! How are you?
**AI:** I'm doing well, thank you for asking! How can I help you today?

## 2026-03-06 19:20:18 UTC
**Human:** What did I just say?
**AI:** You said "Hello! How are you?"

Features

Semantic Search

# Find relevant past conversations
results = memory.recall("What did we discuss about databases?")
for r in results:
    print(f"[{r['score']:.2f}] {r['content']}")

Custom Paths

memory = SoulMemory(
    soul_path="agents/assistant/SOUL.md",
    memory_path="agents/assistant/MEMORY.md",
)

Message Format

# Return as LangChain message objects (for chat models)
memory = SoulMemory(return_messages=True)

Conversation Window

# Only include last 5 exchanges in context
memory = SoulMemory(k=5)

Custom Prefixes

memory = SoulMemory(
    human_prefix="User",
    ai_prefix="Assistant",
)

API Reference

SoulMemory

SoulMemory(
    soul_path="SOUL.md",        # Path to agent identity file
    memory_path="MEMORY.md",    # Path to conversation log
    human_prefix="Human",       # Prefix for human messages
    ai_prefix="AI",             # Prefix for AI messages
    memory_key="history",       # Key for memory in chain
    input_key="input",          # Key for human input
    output_key="output",        # Key for AI output
    return_messages=False,      # Return as Message objects
    k=10,                       # Number of recent exchanges to include
    use_hybrid=True,            # Use soul-agent RAG+RLM
    provider="anthropic",       # LLM provider for hybrid retrieval
)

Methods

Method	Description
save_context(inputs, outputs)	Save a conversation exchange
load_memory_variables(inputs)	Load memory for chain
clear()	Clear all conversation history
recall(query, limit=5)	Semantic search over history
get_buffer_string()	Get full history as string

The Soul Ecosystem

Package	Framework	PyPI
soul-agent	Core library	pip install soul-agent
crewai-soul	CrewAI	pip install crewai-soul
langchain-soul	LangChain	pip install langchain-soul

Links

• soul.py — Core memory library
• crewai-soul — CrewAI integration
• The Menon Lab — Research & tools

License

MIT