🧠 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)
recall_by_emotion()	Retrieve memories tagged with a specific emotion
get_associated()	Retrieve memories linked to a given memory
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

Emotional Tagging

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

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")

Memory Associations

Like the human brain, SoulMemory automatically links related memories:

mem.remember("Went to the gym in the morning")
mem.remember("Worked out at the gym today")
# → automatically linked (similar meaning)

# See what's connected to a memory
results = mem.recall("gym")
linked = mem.get_associated(results[0]["id"])

# Or link memories manually
mem.associate(id_a, id_b)

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?")

recall_by_emotion(emotion, limit=10)

Retrieve memories tagged with a specific emotion ('joy', 'sadness', 'anger', 'fear', 'surprise', 'disgust', 'neutral').

joy_memories = mem.recall_by_emotion('joy')

get_associated(memory_id, limit=5)

Retrieve memories associated with a given memory.

linked = mem.get_associated(memory_id)

associate(memory_id_a, memory_id_b, strength=1.0)

Manually link two memories together.

mem.associate(id_a, id_b)

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

---