📚 Documentation Guide

Choose your starting point:

| I want to... | Read this | Time | |---|---|---| | Get started quickly | REDDIT_QUICKSTART.md | 5 min | | Install the system | INSTALL.md | 10 min | | Understand configuration | CONFIGURATION.md | 15 min | | Check system health | TESTING.md | 10 min | | Use the API | API.md | 20 min | | Deploy to production | DEPLOYMENT.md | 15 min | | Fix a problem | TROUBLESHOOTING.md | varies | | See examples | examples/README.md | 15 min |

🚀 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:

| Provider | Speed | Quality | Cost | |----------|-------|---------|------| | Ollama (local) | ⚡⚡ | ⭐⭐⭐ | FREE | | LM Studio (local) | ⚡ | ⭐⭐⭐⭐ | FREE | | OpenAI (cloud) | ⚡⚡ | ⭐⭐⭐⭐⭐ | $$$ |

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:

| Feature | Traditional | AI Memory System | |---------|-------------|------------------| | Memory Extraction | Manual/Static | LLM-powered intelligent extraction | | Filtering | Simple keyword matching | Multi-layer semantic + relevance scoring | | Memory Injection | All available memories | Smart filtering - only