Persistent AI Memory System v2.0.0

🌟 Community Call to Action: Have you made improvements or additions to this system? Submit a pull request! Every contributor will be properly credited in the final product.

GITHUB LINK - https://github.com/savantskie/persistent-ai-memory.git

What's New in v2.0.0 (September 20, 2026)

Full Feature Parity Release -- PAM is now fully in sync with the internal production system. Every feature from months of real-world use is now public.

• Core Identity System -- Distills a complete profile of who the user is across all conversations. Pulls from curated memories, the OpenWebUI memory table, and archived databases. Updates incrementally rather than starting from scratch each time.
• Automated Memory Maintenance -- Background tasks reformat old memories, detect contradictions and updates, and link orphaned memories to their source conversations. Includes a backlog processor that deduplicates entries, fills in missing metadata, and re-ranks memory importance using the LLM.
• Task Coordinator -- Centralized scheduler replaces ad-hoc sleep loops. Proper concurrency control with per-database locking and LLM call gating. Detects user activity and waits until idle to run heavy work.
• Vision Support -- Precomputes image embeddings via a separate vision server so the main LLM does not need mmproj loaded. Caches embeddings for cross-turn injection. Works with llama.cpp, LM Studio, and any OpenAI-compatible embedding provider.
• Cross-System Deduplication -- When promoting short-term memories to long-term storage, checks for exact and semantic duplicates. Merges related memories instead of creating redundant copies.
• Heartbeat-Based Idle Detection -- The system respects when you are actively using it and delays heavy background tasks until you are idle.
• New Utility Tools -- Interactive model-specific memory deletion (pam_delete_model_memories.py), memory export to text files (export_memories.py), and MCP tool call filtering (filter_tool_calls.py).
• Normalization Migration -- One-time migration that normalizes user and model IDs for consistent multi-user isolation.

Upgrade from v1.5.0: Drop-in replacement. Replace your existing PAM files with the new versions. The database schema is backward compatible.

What's New in v1.5.0 (March 28, 2026)

Major Architectural Rewrite: OpenWebUI-Native Integration

• ✅ OpenWebUI-first design - AI Memory System now deeply integrated into OpenWebUI via plugin (primary deployment method)
• ✅ Advanced short-term memory - sophisticated memory extraction, filtering, and injection for chat conversations
• ✅ User ID & Model ID isolation - strict multi-tenant support with configurable enforcement for security and tracking
• ✅ Complete system portability - all hardcoded paths replaced with environment variables (works anywhere)
• ✅ Generic class names - removed all Friday-specific branding (FridayMemorySystem → AIMemorySystem)
• ✅ Production-ready - enhanced error handling, validation, and logging throughout

Upgrade from v1.1.0: See CHANGELOG.md for migration guide.

📚 Documentation Guide

Choose your starting point:

🚀 Quick Start (30 seconds)

Installation

# Linux/macOS
pip install git+https://github.com/savantskie/persistent-ai-memory.git

# Windows (same command, just use Command Prompt or PowerShell)
pip install git+https://github.com/savantskie/persistent-ai-memory.git

First Validation

python tests/test_health_check.py

Expected output:

[✓] Imported ai_memory_core
[✓] Found embedding_config.json
[✓] System health check passed
[✓] All health checks passed! System is ready to use.

💡 What This System Does

Persistent AI Memory provides sophisticated memory management for AI assistants:

• 📝 OpenWebUI Short-Term Memory Plugin - Intelligent memory extraction and injection directly in chat conversations
• 🧠 Persistent Memory Storage - SQLite databases for structured, searchable long-term memories
• 🔍 Semantic Search - Vector embeddings for intelligent memory retrieval and relevance scoring
• 💬 Conversation Tracking - Multi-platform conversation history capture with context linking
• 🎯 Smart Memory Filtering - Advanced blacklist/whitelist and relevance scoring to inject only what matters
• 🧮 Tool Call Logging - Track and analyze AI tool usage patterns and performance
• 🔄 Self-Reflection - AI insights into its own behavior and memory patterns
• 📱 Multi-Platform Support - Works with OpenWebUI (primary), LM Studio, VS Code, and any MCP-compatible assistant
• 🎨 MCP Server - Standard Model Context Protocol for cross-platform integration

⚙️ System Architecture

Five Specialized Databases

~/.ai_memory/
├── conversations.db      # Chat messages and conversation history
├── ai_memories.db       # Curated long-term memories
├── schedule.db          # Appointments and reminders
├── mcp_tool_calls.db    # Tool usage logs and reflections
└── vscode_project.db    # Development session context

Configuration Files

~/.ai_memory/
├── embedding_config.json   # Embedding provider setup
└── memory_config.json      # Memory system defaults

🎯 Core Features

Memory Operations

• store_memory() - Save important information persistently
• search_memories() - Find memories using semantic search
• list_recent_memories() - Get recent memories without searching

Conversation Tracking

• store_conversation() - Store user/assistant messages
• search_conversations() - Search through conversation history
• get_conversation_history() - Retrieve chronological conversations

Tool Integration

• log_tool_call() - Record MCP tool invocations
• get_tool_call_history() - Analyze tool usage patterns
• reflect_on_tool_usage() - Get AI insights on tool patterns

System Health

• get_system_health() - Check databases, embeddings, providers
• built-in health check - python tests/test_health_check.py

🔌 Embedding Providers

Choose your embedding service:

See CONFIGURATION.md for setup instructions for each provider.

� Important: User ID & Model ID Requirements

All memory operations require user_id and model_id parameters for data isolation and tracking.

This ensures:

• ✅ Multi-user safety - Each user's memories are completely isolated
• ✅ Model tracking - Different AI models can maintain separate memories
• ✅ Audit trail - All operations are traceable to the user and model

Configuration Options

By default, user_id and model_id are required. You can change this in memory_config.json:

{
  "tool_requirements": {
    "require_user_id": true,
    "require_model_id": true,
    "default_user_id": "default_user",
    "default_model_id": "default_model"
  }
}

• require_user_id/require_model_id: true → Strict mode (recommended for production, security-focused, or multi-user systems)
• require_user_id/require_model_id: false → Use defaults instead (simpler for single-user/single-model setups)

For AI Assistants: Auto-Fill in System Prompt

To make your AI automatically provide these values, add this to its system prompt:

When using memory system tools (store_memory, search_memories, etc.), 
ALWAYS include these parameters:
- user_id='your_user_identifier' (e.g., 'nate_user_1')
- model_id='your_model_name' (e.g., 'llama-2:7b' or 'gpt-4')

If the actual values are unknown, use safe defaults:
- user_id='default_user'
- model_id='default_model'

This isolates memories per user and tracks which AI model generated each memory.

Examples

With user_id and model_id:

# Memories are stored with full isolation
await system.store_memory(
    "User likes Python", 
    user_id="alice", 
    model_id="gpt-4"
)

# Search returns only this user's memories for this model
results = await system.search_memories(
    "programming", 
    user_id="alice", 
    model_id="gpt-4"
)

Without strict requirements (if disabled):

# Uses defaults from memory_config.json
await system.store_memory("User likes Python")  # user_id="default_user", model_id="default_model"

See API.md for complete parameter documentation.

�🔄 Integration Methods (Choose One)

1. OpenWebUI Plugin (Recommended)

Primary deployment method - Deep integration for sophisticated memory management:

• Deploy ai_memory_short_term.py as an OpenWebUI Function
• Automatically extracts memories from conversations
• Intelligently injects relevant memories before AI response
• Configurable memory scoring, filtering, and injection preferences
• No additional setup required beyond copying file into OpenWebUI Functions editor

Installation:

1. In OpenWebUI: Settings → Functions → +New Function
2. Paste entire ai_memory_short_term.py file
3. Set trigger to Inlet (runs before model response)
4. Configure memory preferences via function settings

2. MCP Server (Alternative Platforms)

Use with any MCP-compatible AI assistant (Claude, custom integrations, etc.):

# Via mcpo
python -m ai_memory_mcp_server

# Or make streamable for OpenWebUI's alternative integration
# (OpenWebUI supports both plugin and streamable MCP methods)

3. Standalone Library (Custom Implementations)

Use memory capabilities directly in your Python code:

from ai_memory_core import AIMemorySystem
system = AIMemorySystem()
await system.store_memory("Important information", user_id="user1", model_id="model1")
results = await system.search_memories("query", user_id="user1", model_id="model1")

🛠️ Development & Examples

Ready-to-use examples:

python examples/basic_usage.py          # Store and search memories
python examples/advanced_usage.py       # Conversation tracking and tool logging
python examples/performance_tests.py    # Benchmark operations

Full API reference: API.md

📖 Learning Resources

• New to AI memory systems? → REDDIT_QUICKSTART.md
• Troubleshooting issues? → TROUBLESHOOTING.md
• Need configuration help? → CONFIGURATION.md
• Want to deploy to production? → DEPLOYMENT.md
• Need the full API? → API.md

� System Sophistication

This is a significantly enhanced version of traditional memory systems:

Result: An AI assistant that truly learns from and adapts to your preferences over time.

�🤝 Contributing

We welcome contributions! See CONTRIBUTORS.md for:

• Development setup instructions
• How to run tests
• Code style guidelines
• Contribution process

📄 License

MIT License - Feel free to use this in your own AI projects!

See LICENSE for details.

🙏 Acknowledgments

This project represents a unique collaboration:

• @savantskie - Project vision, architecture, testing
• GitHub Copilot - Core implementation and system design
• ChatGPT - Architectural guidance and insights

Special thanks to the AI and open-source communities for inspiration and support.

📞 Need Help?

1. Start with: TESTING.md → Run health check
2. Then check: TROUBLESHOOTING.md → Find your issue
3. Or visit: COMMUNITY.md → Get help from community
4. Or open: GitHub Issues

⭐ If this project helps you build better AI assistants, please give it a star!

Built with determination, debugged with patience, designed for the future of AI.