llamaindex-soul 🧠

The soul ecosystem for LlamaIndex.

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 llamaindex-soul

This automatically installs:

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

Quick Start

Basic Memory

from llamaindex_soul import SoulChatStore
from llama_index.core.memory import ChatMemoryBuffer

# Create markdown-based chat storage with full RAG+RLM
chat_store = SoulChatStore()
memory = ChatMemoryBuffer.from_defaults(
    token_limit=3000,
    chat_store=chat_store,
    chat_store_key="user1",
)

# Use it with your agent
from llama_index.core.agent import FunctionAgent

agent = FunctionAgent(tools=tools, llm=llm)
await agent.run("Hello!", memory=memory)

Your chat history is stored in markdown files — human-readable, git-versionable, no database required.

Semantic Search

# Search past conversations
results = chat_store.recall("user1", "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 llamaindex_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 llamaindex_soul import SoulMateChatStore
from llama_index.core.memory import ChatMemoryBuffer

# Connect to SoulMate cloud
chat_store = SoulMateChatStore(api_key="your-key")
memory = ChatMemoryBuffer.from_defaults(
    token_limit=3000,
    chat_store=chat_store,
    chat_store_key="user1",
)

# Same interface, managed infrastructure
await agent.run("Hello!", memory=memory)

Factory Function

from llamaindex_soul import create_chat_store

# Local file-based (default)
store = create_chat_store()

# SoulMate managed
store = create_chat_store("soulmate", api_key="...")

Architecture

┌──────────────────────────────────────────────────────────┐
│                    llamaindex-soul                        │
│                                                          │
│   ┌─────────────┐     ┌───────────────┐                 │
│   │SoulChatStore│     │SoulMateChatStore│               │
│   │  (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
• llamaindex-soul — LlamaIndex integration (this package)
• SoulMate — Managed cloud service

License

MIT