Skip to content
Back to search

persistent-ai-memory

A persistent local memory for AI, LLMs, or Copilot in VS Code.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/savantskie--persistent-ai-memory/badge.svg)](/listings/savantskie--persistent-ai-memory)

HTML

<a href="/listings/savantskie--persistent-ai-memory"><img src="/api/listings/savantskie--persistent-ai-memory/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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 was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 374 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Persistent AI Memory System v2.0.0
  2. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  3. [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
  4. [![Release](https://img.shields.io/badge/release-v2.0.0-green.svg)](https://github.com/savantskie/persistent-ai-memory)
  5. > 🌟 **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.
  6. **GITHUB LINK** - https://github.com/savantskie/persistent-ai-memory.git
  7. ---
  8. ## What's New in v2.0.0 (September 20, 2026)
  9. **Full Feature Parity Release** -- PAM is now fully in sync with the internal
  10. production system. Every feature from months of real-world use is now public.
  11. - **Core Identity System** -- Distills a complete profile of who the user is
  12. across all conversations. Pulls from curated memories, the OpenWebUI memory
  13. table, and archived databases. Updates incrementally rather than starting
  14. from scratch each time.
  15. - **Automated Memory Maintenance** -- Background tasks reformat old memories,
  16. detect contradictions and updates, and link orphaned memories to their source
  17. conversations. Includes a backlog processor that deduplicates entries, fills
  18. in missing metadata, and re-ranks memory importance using the LLM.
  19. - **Task Coordinator** -- Centralized scheduler replaces ad-hoc sleep loops.
  20. Proper concurrency control with per-database locking and LLM call gating.
  21. Detects user activity and waits until idle to run heavy work.
  22. - **Vision Support** -- Precomputes image embeddings via a separate vision
  23. server so the main LLM does not need mmproj loaded. Caches embeddings for
  24. cross-turn injection. Works with llama.cpp, LM Studio, and any
  25. OpenAI-compatible embedding provider.
  26. - **Cross-System Deduplication** -- When promoting short-term memories to
  27. long-term storage, checks for exact and semantic duplicates. Merges related
  28. memories instead of creating redundant copies.
  29. - **Heartbeat-Based Idle Detection** -- The system respects when you are
  30. actively using it and delays heavy background tasks until you are idle.
  31. - **New Utility Tools** -- Interactive model-specific memory deletion
  32. (pam_delete_model_memories.py), memory export to text files
  33. (export_memories.py), and MCP tool call filtering (filter_tool_calls.py).
  34. - **Normalization Migration** -- One-time migration that normalizes user and
  35. model IDs for consistent multi-user isolation.
  36. **Upgrade from v1.5.0:** Drop-in replacement. Replace your existing PAM files
  37. with the new versions. The database schema is backward compatible.
  38. ---
  39. ## What's New in v1.5.0 (March 28, 2026)
  40. **Major Architectural Rewrite: OpenWebUI-Native Integration**
  41. - ✅ **OpenWebUI-first design** - AI Memory System now deeply integrated into OpenWebUI via plugin (primary deployment method)
  42. - ✅ **Advanced short-term memory** - sophisticated memory extraction, filtering, and injection for chat conversations
  43. - ✅ **User ID & Model ID isolation** - strict multi-tenant support with configurable enforcement for security and tracking
  44. - ✅ **Complete system portability** - all hardcoded paths replaced with environment variables (works anywhere)
  45. - ✅ **Generic class names** - removed all Friday-specific branding (FridayMemorySystem → AIMemorySystem)
  46. - ✅ **Production-ready** - enhanced error handling, validation, and logging throughout
  47. **Upgrade from v1.1.0:** See [CHANGELOG.md](CHANGELOG.md) for migration guide.
  48. ---
  49. ## 📚 Documentation Guide
  50. **Choose your starting point:**
  51. | **I want to...** | **Read this** | **Time** |
  52. |---|---|---|
  53. | Get started quickly | [REDDIT_QUICKSTART.md](REDDIT_QUICKSTART.md) | 5 min |
  54. | Install the system | [INSTALL.md](INSTALL.md) | 10 min |
  55. | Understand configuration | [CONFIGURATION.md](CONFIGURATION.md) | 15 min |
  56. | Check system health | [TESTING.md](TESTING.md) | 10 min |
  57. | Use the API | [API.md](API.md) | 20 min |
  58. | Deploy to production | [DEPLOYMENT.md](DEPLOYMENT.md) | 15 min |
  59. | Fix a problem | [TROUBLESHOOTING.md](TROUBLESHOOTING.md) | varies |
  60. | See examples | [examples/README.md](examples/README.md) | 15 min |
  61. ---
  62. ## 🚀 Quick Start (30 seconds)
  63. ### Installation
  64. ```bash
  65. # Linux/macOS
  66. pip install git+https://github.com/savantskie/persistent-ai-memory.git
  67. # Windows (same command, just use Command Prompt or PowerShell)
  68. pip install git+https://github.com/savantskie/persistent-ai-memory.git
  69. ```
  70. ### First Validation
  71. ```bash
  72. python tests/test_health_check.py
  73. ```
  74. Expected output:
  75. ```
  76. [✓] Imported ai_memory_core
  77. [✓] Found embedding_config.json
  78. [✓] System health check passed
  79. [✓] All health checks passed! System is ready to use.
  80. ```
  81. ---
  82. ## 💡 What This System Does
  83. **Persistent AI Memory** provides sophisticated memory management for AI assistants:
  84. - 📝 **OpenWebUI Short-Term Memory Plugin** - Intelligent memory extraction and injection directly in chat conversations
  85. - 🧠 **Persistent Memory Storage** - SQLite databases for structured, searchable long-term memories
  86. - 🔍 **Semantic Search** - Vector embeddings for intelligent memory retrieval and relevance scoring
  87. - 💬 **Conversation Tracking** - Multi-platform conversation history capture with context linking
  88. - 🎯 **Smart Memory Filtering** - Advanced blacklist/whitelist and relevance scoring to inject only what matters
  89. - 🧮 **Tool Call Logging** - Track and analyze AI tool usage patterns and performance
  90. - 🔄 **Self-Reflection** - AI insights into its own behavior and memory patterns
  91. - 📱 **Multi-Platform Support** - Works with OpenWebUI (primary), LM Studio, VS Code, and any MCP-compatible assistant
  92. - 🎨 **MCP Server** - Standard Model Context Protocol for cross-platform integration
  93. ---
  94. ## ⚙️ System Architecture
  95. ### Five Specialized Databases
  96. ```
  97. ~/.ai_memory/
  98. ├── conversations.db # Chat messages and conversation history
  99. ├── ai_memories.db # Curated long-term memories
  100. ├── schedule.db # Appointments and reminders
  101. ├── mcp_tool_calls.db # Tool usage logs and reflections
  102. └── vscode_project.db # Development session context
  103. ```
  104. ### Configuration Files
  105. ```
  106. ~/.ai_memory/
  107. ├── embedding_config.json # Embedding provider setup
  108. └── memory_config.json # Memory system defaults
  109. ```
  110. ---
  111. ## 🎯 Core Features
  112. ### Memory Operations
  113. - `store_memory()` - Save important information persistently
  114. - `search_memories()` - Find memories using semantic search
  115. - `list_recent_memories()` - Get recent memories without searching
  116. ### Conversation Tracking
  117. - `store_conversation()` - Store user/assistant messages
  118. - `search_conversations()` - Search through conversation history
  119. - `get_conversation_history()` - Retrieve chronological conversations
  120. ### Tool Integration
  121. - `log_tool_call()` - Record MCP tool invocations
  122. - `get_tool_call_history()` - Analyze tool usage patterns
  123. - `reflect_on_tool_usage()` - Get AI insights on tool patterns
  124. ### System Health
  125. - `get_system_health()` - Check databases, embeddings, providers
  126. - `built-in health check` - `python tests/test_health_check.py`
  127. ---
  128. ## 🔌 Embedding Providers
  129. Choose your embedding service:
  130. | Provider | Speed | Quality | Cost |
  131. |----------|-------|---------|------|
  132. | **Ollama** (local) | ⚡⚡ | ⭐⭐⭐ | FREE |
  133. | **LM Studio** (local) | ⚡ | ⭐⭐⭐⭐ | FREE |
  134. | **OpenAI** (cloud) | ⚡⚡ | ⭐⭐⭐⭐⭐ | $$$ |
  135. See [CONFIGURATION.md](CONFIGURATION.md) for setup instructions for each provider.
  136. ---
  137. ## � Important: User ID & Model ID Requirements
  138. **All memory operations require `user_id` and `model_id` parameters for data isolation and tracking.**
  139. This ensures:
  140. - ✅ **Multi-user safety** - Each user's memories are completely isolated
  141. - ✅ **Model tracking** - Different AI models can maintain separate memories
  142. - ✅ **Audit trail** - All operations are traceable to the user and model
  143. ### Configuration Options
  144. By default, `user_id` and `model_id` are **required**. You can change this in `memory_config.json`:
  145. ```json
  146. {
  147. "tool_requirements": {
  148. "require_user_id": true,
  149. "require_model_id": true,
  150. "default_user_id": "default_user",
  151. "default_model_id": "default_model"
  152. }
  153. }
  154. ```
  155. - `require_user_id/require_model_id: true` → Strict mode (recommended for production, security-focused, or multi-user systems)
  156. - `require_user_id/require_model_id: false` → Use defaults instead (simpler for single-user/single-model setups)
  157. ### For AI Assistants: Auto-Fill in System Prompt
  158. To make your AI automatically provide these values, add this to its **system prompt**:
  159. ```
  160. When using memory system tools (store_memory, search_memories, etc.),
  161. ALWAYS include these parameters:
  162. - user_id='your_user_identifier' (e.g., 'nate_user_1')
  163. - model_id='your_model_name' (e.g., 'llama-2:7b' or 'gpt-4')
  164. If the actual values are unknown, use safe defaults:
  165. - user_id='default_user'
  166. - model_id='default_model'
  167. This isolates memories per user and tracks which AI model generated each memory.
  168. ```
  169. ### Examples
  170. **With user_id and model_id:**
  171. ```python
  172. # Memories are stored with full isolation
  173. await system.store_memory(
  174. "User likes Python",
  175. user_id="alice",
  176. model_id="gpt-4"
  177. )
  178. # Search returns only this user's memories for this model
  179. results = await system.search_memories(
  180. "programming",
  181. user_id="alice",
  182. model_id="gpt-4"
  183. )
  184. ```
  185. **Without strict requirements (if disabled):**
  186. ```python
  187. # Uses defaults from memory_config.json
  188. await system.store_memory("User likes Python") # user_id="default_user", model_id="default_model"
  189. ```
  190. See [API.md](API.md) for complete parameter documentation.
  191. ---
  192. ## �🔄 Integration Methods (Choose One)
  193. ### 1. OpenWebUI Plugin (Recommended)
  194. **Primary deployment method** - Deep integration for sophisticated memory management:
  195. - Deploy `ai_memory_short_term.py` as an OpenWebUI Function
  196. - Automatically extracts memories from conversations
  197. - Intelligently injects relevant memories before AI response
  198. - Configurable memory scoring, filtering, and injection preferences
  199. - No additional setup required beyond copying file into OpenWebUI Functions editor
  200. **Installation:**
  201. 1. In OpenWebUI: **Settings → Functions → +New Function**
  202. 2. Paste entire `ai_memory_short_term.py` file
  203. 3. Set trigger to `Inlet` (runs before model response)
  204. 4. Configure memory preferences via function settings
  205. ### 2. MCP Server (Alternative Platforms)
  206. Use with any MCP-compatible AI assistant (Claude, custom integrations, etc.):
  207. ```bash
  208. # Via mcpo
  209. python -m ai_memory_mcp_server
  210. # Or make streamable for OpenWebUI's alternative integration
  211. # (OpenWebUI supports both plugin and streamable MCP methods)
  212. ```
  213. ### 3. Standalone Library (Custom Implementations)
  214. Use memory capabilities directly in your Python code:
  215. ```python
  216. from ai_memory_core import AIMemorySystem
  217. system = AIMemorySystem()
  218. await system.store_memory("Important information", user_id="user1", model_id="model1")
  219. results = await system.search_memories("query", user_id="user1", model_id="model1")
  220. ```
  221. ---
  222. ## 🛠️ Development & Examples
  223. Ready-to-use examples:
  224. ```bash
  225. python examples/basic_usage.py # Store and search memories
  226. python examples/advanced_usage.py # Conversation tracking and tool logging
  227. python examples/performance_tests.py # Benchmark operations
  228. ```
  229. Full API reference: [API.md](API.md)
  230. ---
  231. ## 📖 Learning Resources
  232. - **New to AI memory systems?** → [REDDIT_QUICKSTART.md](REDDIT_QUICKSTART.md)
  233. - **Troubleshooting issues?** → [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
  234. - **Need configuration help?** → [CONFIGURATION.md](CONFIGURATION.md)
  235. - **Want to deploy to production?** → [DEPLOYMENT.md](DEPLOYMENT.md)
  236. - **Need the full API?** → [API.md](API.md)
  237. ---
  238. ## � System Sophistication
  239. This is a significantly enhanced version of traditional memory systems:
  240. | Feature | Traditional | AI Memory System |
  241. |---------|-------------|------------------|
  242. | Memory Extraction | Manual/Static | LLM-powered intelligent extraction |
  243. | Filtering | Simple keyword matching | Multi-layer semantic + relevance scoring |
  244. | Memory Injection | All available memories | Smart filtering - only inject relevant |
  245. | Duplicate Prevention | Text matching | Embedding-based semantic deduplication |
  246. | Importance Scoring | Not tracked | Dynamic importance analysis |
  247. | Memory Normalization | N/A | Automatic format standardization |
  248. | Context Awareness | Limited | Full conversation context integration |
  249. | Tool Integration | Basic logging | Deep reflection and pattern analysis |
  250. | Error Handling | Minimal | Comprehensive validation and recovery |
  251. | Performance | N/A | Optimized with async operations |
  252. **Result:** An AI assistant that truly learns from and adapts to your preferences over time.
  253. ---
  254. ## �🤝 Contributing
  255. We welcome contributions! See [CONTRIBUTORS.md](CONTRIBUTORS.md) for:
  256. - Development setup instructions
  257. - How to run tests
  258. - Code style guidelines
  259. - Contribution process
  260. ---
  261. ## 📄 License
  262. MIT License - Feel free to use this in your own AI projects!
  263. See [LICENSE](LICENSE) for details.
  264. ---
  265. ## 🙏 Acknowledgments
  266. This project represents a unique collaboration:
  267. - **@savantskie** - Project vision, architecture, testing
  268. - **GitHub Copilot** - Core implementation and system design
  269. - **ChatGPT** - Architectural guidance and insights
  270. **Special thanks** to the AI and open-source communities for inspiration and support.
  271. ---
  272. ## 📞 Need Help?
  273. 1. **Start with**: [TESTING.md](TESTING.md) → Run health check
  274. 2. **Then check**: [TROUBLESHOOTING.md](TROUBLESHOOTING.md) → Find your issue
  275. 3. **Or visit**: [COMMUNITY.md](COMMUNITY.md) → Get help from community
  276. 4. **Or open**: [GitHub Issues](https://github.com/savantskie/persistent-ai-memory/issues)
  277. ---
  278. **⭐ If this project helps you build better AI assistants, please give it a star!**
  279. Built with determination, debugged with patience, designed for the future of AI.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.