Metadata-Version: 2.4
Name: soulmemory
Version: 0.2.0
Summary: A memory system for AI companions that mimics human memory
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sentence-transformers
Requires-Dist: sqlite-vec
Requires-Dist: numpy
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

# 🧠 SoulMemory

<div align="center">

**A memory system for AI companions that mimics human memory: remembers, recalls, forgets, and consolidates.**

</div>

<div align="center">

[![PyPI version](https://img.shields.io/pypi/v/soulmemory.svg)](https://pypi.org/project/soulmemory/)
[![Python](https://img.shields.io/badge/Python-3.9%2B-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

</div>

---

## 🎯 Why SoulMemory?

Most AI chatbots have **no memory**. Every conversation starts from zero. SoulMemory gives your AI a **persistent, human-like memory** that:

- ✅ **Remembers** important events (and auto-detects what's important)
- 🔍 **Recalls** relevant memories using semantic search
- ⏳ **Forgets** trivial things naturally over time
- 🗜️ **Consolidates** old memories to save space
- 🛡️ **Protects** critical memories from ever being forgotten

## ✨ Features

| Feature               | Description                                              |
| --------------------- | -------------------------------------------------------- |
| `remember()`          | Store memories with auto importance detection            |
| `recall()`            | Semantic search (understands meaning, not just keywords) |
| `recall_by_emotion()` | Retrieve memories tagged with a specific emotion         |
| `decay()`             | Natural forgetting based on time and usage               |
| `consolidate()`       | Compress similar old memories into summaries             |
| `stats()`             | Memory statistics and insights                           |

## 📦 Installation

```bash
pip install soulmemory
```

Or install from source:

```bash
git clone https://github.com/YOUR_USERNAME/soulmemory.git
cd soulmemory
pip install -e .
```

## 🚀 Quick Start

```python
from soulmemory import SoulMemory

# Initialize
mem = SoulMemory("my_memory.db")

# Store memories (importance auto-detected)
mem.remember("My girlfriend proposed to me today!")
mem.remember("Had a sandwich for lunch")

# Search semantically
results = mem.recall("romantic news")
for r in results:
    print(r['content'])  # → "My girlfriend proposed to me today!"

# Clean up
mem.close()
```

## 🧩 Core Concepts

### Memory Levels

| Level       | Behavior        | Example                   |
| ----------- | --------------- | ------------------------- |
| `critical`  | Never forgotten | "My mother passed away"   |
| `important` | Fades slowly    | "Got a promotion at work" |
| `normal`    | Standard decay  | "Meeting with the team"   |
| `trivial`   | Fades quickly   | "It's cloudy today"       |

### Auto Importance Detection

SoulMemory automatically detects how important a memory is:

```python
# No need to specify importance - it's detected
mem.remember("My girlfriend proposed to me!")
# → importance: 0.95, level: critical

mem.remember("It's raining outside")
# → importance: 0.35, level: trivial
```

### Emotional Tagging

SoulMemory automatically detects the emotion of each memory (six basic emotions + neutral):

```python
mem.remember("We won the championship!")
# → emotion: "joy"

mem.remember("My dog passed away")
# → emotion: "sadness"

# Recall memories by emotion
happy_memories = mem.recall_by_emotion("joy")
```

### The Forgetting Curve

Memories fade over time, just like human memory:

```python
# Run the forgetting process
forgotten = mem.decay(decay_rate=0.85, threshold=0.2)
print(f"Forgot {forgotten} memories")
```

The formula:

```
score = importance × (decay_rate ^ days_since_access) + (access_count × 0.05)
```

- More days without access → lower score
- More times accessed → stays "alive"
- Score below threshold → memory is forgotten
- `critical` memories → never decay

## 📚 API Reference

### `remember(content, importance=None, level=None, emotion=None, auto_detect=True)`

Store a new memory.

```python
mem.remember("First date with Ana at the coffee shop")
```

### `recall(query, limit=5)`

Search for relevant memories.

```python
results = mem.recall("what do I know about Ana?")
```

### `decay(decay_rate=0.85, threshold=0.2)`

Run the forgetting process.

```python
forgotten_count = mem.decay()
```

### `consolidate(min_age_days=7, similarity_threshold=0.75)`

Compress old, similar memories.

```python
consolidated = mem.consolidate()
```

### `stats()`

Get memory statistics.

```python
print(mem.stats())
# → {'total_memories': 42, 'by_level': {'critical': 3, ...}}
```

## 🛠️ Use Cases

- 🤖 **AI Companions** that remember your life
- 💬 **Chatbots** with long-term memory
- 🎮 **Game NPCs** that remember player interactions
- 📔 **Personal AI journals** that evolve over time

## 🗺️ Roadmap

- [x] Core memory storage
- [x] Semantic search
- [x] Importance auto-detection
- [x] Decay (forgetting)
- [x] Consolidation
- [ ] Emotional tagging
- [ ] Memory associations
- [ ] Multi-user support

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [sentence-transformers](https://github.com/UKPLab/sentence-transformers) for embeddings
- [sqlite-vec](https://github.com/asg017/sqlite-vec) for vector search

---

<div align="center">

**Made with ❤️ for the AI community**

If you find this useful, please ⭐ star the repository!

</div>
