langchain-soul 🧠

The soul ecosystem for LangChain.

One package, full stack:

• Persistent Memory — Markdown-native, git-versionable, human-readable
• Hybrid Retrieval — RAG + RLM via soul-agent
• Database Intelligence — Auto-generated semantic layers via soul-schema
• Managed Cloud Option — SoulMate handles memory infrastructure for you

Choose Your Setup

Both use the same soul-agent RAG+RLM under the hood.

Install

pip install langchain-soul

This automatically installs:

• soul-agent — Hybrid RAG+RLM memory
• soul-schema — Database semantic layer generator

Quick Start

Basic Memory

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

# Create markdown-based memory with full RAG+RLM
memory = SoulMemory()

# Use it with your chain
chain = ConversationChain(llm=ChatOpenAI(), memory=memory)
response = chain.predict(input="Hello!")

Your conversations are stored in MEMORY.md — human-readable, git-versionable, no database required.

With RunnableWithMessageHistory

from langchain_soul import SoulChatMessageHistory
from langchain_core.runnables.history import RunnableWithMessageHistory

chain_with_history = RunnableWithMessageHistory(
    chain,
    lambda session_id: SoulChatMessageHistory(
        memory_path=f"memory/{session_id}.md"
    ),
)

Semantic Search

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

Database Schema Intelligence

Give your agents understanding of database structure:

from langchain_soul import SchemaMemory

# Connect to any SQLAlchemy-compatible database
schema = SchemaMemory("postgresql://user:pass@host/db")

# Auto-generate semantic descriptions using LLM
schema.generate()

# Get context for natural language queries
context = schema.context_for("Show me revenue by region")

SoulMate: Managed Memory (Recommended for Production)

Don't want to manage files? SoulMate is the managed version — same RAG+RLM, zero infrastructure:

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

# Connect to SoulMate cloud
memory = SoulMateMemory(api_key="your-key")
chain = ConversationChain(llm=ChatOpenAI(), memory=memory)

# Same interface, managed infrastructure
response = chain.predict(input="Hello!")

Factory Function

from langchain_soul import create_memory

# Local file-based (default)
memory = create_memory()

# SoulMate managed
memory = create_memory("soulmate", api_key="...")

Architecture

┌──────────────────────────────────────────────────────────┐
│                     langchain-soul                        │
│                                                          │
│   ┌─────────────┐     ┌───────────────┐                 │
│   │ SoulMemory  │     │SoulMateMemory │                 │
│   │  (local)    │     │  (managed)    │                 │
│   └──────┬──────┘     └───────┬───────┘                 │
│          │                    │                          │
│          ▼                    ▼                          │
│   ┌─────────────────────────────────────────────────┐   │
│   │              soul-agent (RAG + RLM)             │   │
│   └─────────────────────────────────────────────────┘   │
│                                                          │
│   ┌──────────────────┐    ┌─────────────────────────┐   │
│   │   soul-schema    │    │    SoulMate API         │   │
│   │ (db intelligence)│    │  (managed memory)       │   │
│   └──────────────────┘    └─────────────────────────┘   │
└──────────────────────────────────────────────────────────┘

Part of the Soul Ecosystem

• soul-agent — Core RAG + RLM library
• soul-schema — Database semantic layer generator
• crewai-soul — CrewAI integration
• langchain-soul — LangChain integration (this package)
• llamaindex-soul — LlamaIndex integration
• SoulMate — Managed cloud service

License

MIT