Metadata-Version: 2.4
Name: llamaindex-soul
Version: 0.1.0
Summary: Markdown-native chat storage for LlamaIndex. Human-readable, git-versionable, powered by soul-agent.
Author-email: "Prahlad G. Menon" <menon.prahlad@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/menonpg/llamaindex-soul
Project-URL: Documentation, https://github.com/menonpg/llamaindex-soul#readme
Project-URL: Repository, https://github.com/menonpg/llamaindex-soul
Keywords: llamaindex,llama-index,memory,chat,ai,agents,llm,markdown,soul,rag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: soul-agent>=0.1.7
Requires-Dist: llama-index-core>=0.10.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"

# 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](https://github.com/menonpg/soul.py).

## Install

```bash
pip install llamaindex-soul
```

## Quick Start

```python
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`:

```markdown
# 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

```python
# 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

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

### Persistence

```python
# 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

```python
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](https://github.com/menonpg/soul.py) | Core library | `pip install soul-agent` |
| [crewai-soul](https://github.com/menonpg/crewai-soul) | CrewAI | `pip install crewai-soul` |
| [langchain-soul](https://github.com/menonpg/langchain-soul) | LangChain | `pip install langchain-soul` |
| **llamaindex-soul** | LlamaIndex | `pip install llamaindex-soul` |

## Links

- [soul.py](https://github.com/menonpg/soul.py) — Core memory library
- [LlamaIndex](https://www.llamaindex.ai/) — LLM application framework
- [The Menon Lab](https://themenonlab.com) — Research & tools

## License

MIT
