humem 0.1.0

A memory management system for AI agents to store and retrieve user interactions

Agent Memory

A memory management system for AI agents to store and retrieve user interactions and preferences.

Features

• 🧠 Persistent Memory Storage: Store conversations, user preferences, facts, and context
• 🔍 Powerful Search: Find memories by content, tags, importance, date ranges, and more
• 🏷️ Flexible Tagging: Organize memories with custom tags
• ⏰ Expiration Support: Set automatic expiration for temporary memories
• 📊 Importance Scoring: Rank memories by importance (0.0 to 1.0)
• 📈 Access Tracking: Monitor memory usage with access counts and timestamps
• 🗃️ Multiple Backends: SQLite (default), PostgreSQL, and other SQLAlchemy-supported databases
• 🔧 Type Safety: Full type hints and Pydantic models
• 🧪 Well Tested: Comprehensive test suite

Installation

pip install agent-memory

For development:

pip install agent-memory[dev]

Quick Start

from agent_memory import AgentMemory, MemoryType

# Initialize the memory system
memory = AgentMemory()

# Add a conversation memory
conversation = memory.add_conversation_memory(
    user_id="user123",
    user_message="I love Python programming",
    agent_response="That's great! Python is a versatile language.",
    importance=0.8,
    tags=["programming", "python"]
)

# Add a user preference
preference = memory.add_user_preference(
    user_id="user123",
    preference="programming_language",
    value="Python"
)

# Search for memories
memories = memory.search_memories(
    user_id="user123",
    content_search="Python",
    min_importance=0.5
)

# Get all user preferences
preferences = memory.get_user_preferences("user123")
print(preferences)  # {"programming_language": "Python"}

Core Concepts

Memory Types

Agent Memory supports different types of memories:

• CONVERSATION: Dialog between user and agent
• USER_PREFERENCE: User settings and preferences
• FACT: Factual information about the user
• CONTEXT: Contextual information for conversations
• GOAL: User goals and objectives
• FEEDBACK: User feedback on agent responses

Memory Properties

Each memory contains:

• id: Unique identifier (UUID)
• user_id: User identifier
• agent_id: Optional agent identifier
• content: The actual memory content
• memory_type: Type of memory (see above)
• importance: Importance score (0.0 to 1.0)
• tags: List of tags for organization
• metadata: Additional structured data
• timestamp: When memory was created
• expires_at: Optional expiration date

Advanced Usage

Custom Database

# Use PostgreSQL
memory = AgentMemory(
    database_url="postgresql://user:pass@localhost/memories"
)

# Use custom SQLite location
memory = AgentMemory(
    database_url="sqlite:///path/to/custom/memories.db"
)

Advanced Searching

from datetime import datetime, timedelta

# Complex search query
memories = memory.search_memories(
    user_id="user123",
    memory_type=MemoryType.CONVERSATION,
    tags=["important", "work"],
    min_importance=0.7,
    created_after=datetime.now() - timedelta(days=7),
    limit=20,
    offset=0
)

Memory Management

# Update memory
updated = memory.update_memory(
    memory_id=conversation.id,
    importance=0.9,
    tags=["programming", "python", "favorite"]
)

# Delete memory
memory.delete_memory(conversation.id)

# Cleanup expired memories
removed_count = memory.cleanup_expired()

Statistics and Analytics

# Get memory statistics
stats = memory.get_memory_stats(user_id="user123")
print(f"Total memories: {stats['total_memories']}")
print(f"By importance: {stats['by_importance']}")
print(f"By type: {stats['by_type']}")

API Reference

AgentMemory

Main class for memory management.

__init__(database_url=None, auto_cleanup=True)

Initialize the memory system.

• database_url: Database connection string (defaults to local SQLite)
• auto_cleanup: Whether to automatically clean expired memories

add_memory(user_id, content, memory_type=CONVERSATION, **kwargs)

Add a new memory.

Parameters:

• user_id (str): User identifier
• content (str): Memory content
• memory_type (MemoryType): Type of memory
• agent_id (str, optional): Agent identifier
• importance (float): Importance score (0.0-1.0)
• tags (List[str]): Tags for organization
• metadata (dict): Additional metadata
• expires_in_days (int): Days until expiration

search_memories(**filters)

Search for memories with flexible filtering.

Filters:

• user_id, agent_id, memory_type
• content_search: Search in content
• tags: Filter by tags
• min_importance, max_importance: Importance range
• created_after, created_before: Date range
• limit, offset: Pagination
• include_expired: Include expired memories

Convenience Methods

• add_conversation_memory(): Add user-agent conversation
• add_user_preference(): Add user preference
• get_user_preferences(): Get all preferences as dict
• get_user_memories(): Get all memories for user
• cleanup_expired(): Remove expired memories
• get_memory_stats(): Get memory statistics

Development

Setup

git clone https://github.com/yourusername/agent-memory.git
cd agent-memory
pip install -e .[dev]

Running Tests

pytest

Code Quality

# Format code
black agent_memory tests

# Sort imports  
isort agent_memory tests

# Type checking
mypy agent_memory

# Linting
flake8 agent_memory tests

Building for PyPI

# Build package
python -m build

# Upload to PyPI (requires API token)
python -m twine upload dist/*

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (pytest)
6. Format code (black . and isort .)
7. Commit changes (git commit -m 'Add amazing feature')
8. Push to branch (git push origin feature/amazing-feature)
9. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

v0.1.0 (Initial Release)

• Core memory management functionality
• SQLite and PostgreSQL support
• Memory types: conversation, preference, fact, context, goal, feedback
• Search and filtering capabilities
• Expiration and cleanup
• Comprehensive test suite

Support

• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions