Persistent AI Memory
A persistent local memory for AI, LLMs, or Copilot in VS Code.
Installation
npx persistent-ai-memoryAsk AI about Persistent AI Memory
Powered by Claude ยท Grounded in docs
I know everything about Persistent AI Memory. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Persistent AI Memory System v1.5.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 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:
| 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 persistentlysearch_memories()- Find memories using semantic searchlist_recent_memories()- Get recent memories without searching
Conversation Tracking
store_conversation()- Store user/assistant messagessearch_conversations()- Search through conversation historyget_conversation_history()- Retrieve chronological conversations
Tool Integration
log_tool_call()- Record MCP tool invocationsget_tool_call_history()- Analyze tool usage patternsreflect_on_tool_usage()- Get AI insights on tool patterns
System Health
get_system_health()- Check databases, embeddings, providersbuilt-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.pyas 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:
- In OpenWebUI: Settings โ Functions โ +New Function
- Paste entire
ai_memory_short_term.pyfile - Set trigger to
Inlet(runs before model response) - 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 inject relevant |
| Duplicate Prevention | Text matching | Embedding-based semantic deduplication |
| Importance Scoring | Not tracked | Dynamic importance analysis |
| Memory Normalization | N/A | Automatic format standardization |
| Context Awareness | Limited | Full conversation context integration |
| Tool Integration | Basic logging | Deep reflection and pattern analysis |
| Error Handling | Minimal | Comprehensive validation and recovery |
| Performance | N/A | Optimized with async operations |
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?
- Start with: TESTING.md โ Run health check
- Then check: TROUBLESHOOTING.md โ Find your issue
- Or visit: COMMUNITY.md โ Get help from community
- 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.
