Metadata-Version: 2.4
Name: langchain-soul
Version: 0.1.0
Summary: Markdown-native memory for LangChain. 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/langchain-soul
Project-URL: Documentation, https://github.com/menonpg/langchain-soul#readme
Project-URL: Repository, https://github.com/menonpg/langchain-soul
Keywords: langchain,memory,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: langchain-core>=0.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"

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

## Install

```bash
pip install langchain-soul
```

## Quick Start

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

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

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

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

### Message Format

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

### Conversation Window

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

### Custom Prefixes

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

## API Reference

### SoulMemory

```python
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](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** | LangChain | `pip install langchain-soul` |

## Links

- [soul.py](https://github.com/menonpg/soul.py) — Core memory library
- [crewai-soul](https://github.com/menonpg/crewai-soul) — CrewAI integration
- [The Menon Lab](https://themenonlab.com) — Research & tools

## License

MIT
