llamaindex-soul 0.1.0

Markdown-native chat storage for LlamaIndex. Human-readable, git-versionable, powered by soul-agent.

llamaindex-soul 🧠

Markdown-native chat storage for LlamaIndex.

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

chat_memory/
├── user1.md
├── user2.md
└── session_abc.md

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

Install

pip install llamaindex-soul

Quick Start

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

# Create markdown-based chat store
chat_store = SoulChatStore()

# Use with ChatMemoryBuffer
memory = ChatMemoryBuffer.from_defaults(
    token_limit=3000,
    chat_store=chat_store,
    chat_store_key="user1",
)

# Use with an agent
from llama_index.core.agent import FunctionAgent

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

After running, check chat_memory/user1.md:

# Chat History: user1

## 2026-03-06 19:30:15 UTC
**User:** Hello!

## 2026-03-06 19:30:17 UTC
**Assistant:** Hi there! How can I help you today?

Features

Multiple Sessions

# Each user/session gets its own file
chat_store = SoulChatStore(storage_dir="./chats")

chat_store.add_message("alice", ChatMessage(role=MessageRole.USER, content="Hi"))
chat_store.add_message("bob", ChatMessage(role=MessageRole.USER, content="Hello"))
# Creates: ./chats/alice.md, ./chats/bob.md

Semantic Search

# Find relevant past conversations
results = chat_store.recall("user1", "database recommendations")
for r in results:
    print(f"[{r['score']:.2f}] {r['content']}")

Persistence

# Already persists on every write, but you can force it
chat_store.persist()

# Load from existing directory
chat_store = SoulChatStore.from_persist_path("./chat_memory")

API Reference

SoulChatStore

SoulChatStore(
    storage_dir="./chat_memory",  # Where to store chat files
    use_hybrid=True,              # Enable soul-agent RAG+RLM
    provider="anthropic",         # LLM provider for retrieval
)

Methods

Method	Description
add_message(key, message)	Add a message to a session
get_messages(key)	Get all messages for a session
set_messages(key, messages)	Set messages (overwrites)
delete_messages(key)	Delete all messages for a session
delete_last_message(key)	Delete the last message
delete_message(key, idx)	Delete message at index
get_keys()	Get all session keys
recall(key, query, limit=5)	Semantic search over history
persist()	Force persist to disk

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
llamaindex-soul	LlamaIndex	pip install llamaindex-soul

Links

• soul.py — Core memory library
• LlamaIndex — LLM application framework
• The Menon Lab — Research & tools

License

MIT