🧠 SoulMemory

---

🎯 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)
decay()	Natural forgetting based on time and usage
consolidate()	Compress similar old memories into summaries
stats()	Memory statistics and insights

📦 Installation

pip install soulmemory

Or install from source:

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

🚀 Quick Start

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:

# 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

The Forgetting Curve

Memories fade over time, just like human memory:

# 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.

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

recall(query, limit=5)

Search for relevant memories.

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

decay(decay_rate=0.85, threshold=0.2)

Run the forgetting process.

forgotten_count = mem.decay()

consolidate(min_age_days=7, similarity_threshold=0.75)

Compress old, similar memories.

consolidated = mem.consolidate()

stats()

Get memory statistics.

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

• Core memory storage
• Semantic search
• Importance auto-detection
• Decay (forgetting)
• 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 file for details.

🙏 Acknowledgments

• sentence-transformers for embeddings
• sqlite-vec for vector search

---