# Memori
**The Open-Source Memory Layer for AI Agents & Multi-Agent Systems v1.2**
*Give your AI agents structured, persistent memory with intelligent context injection - no more repeating yourself!*
[](https://badge.fury.io/py/memori)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
---
## 🎯 Philosophy
- **Second-memory for all your LLM work** - Never repeat context again
- **Dual-mode memory injection** - Conscious short-term memory + Auto intelligent search
- **Flexible database connections** - SQLite, PostgreSQL, MySQL support
- **Pydantic-based intelligence** - Structured memory processing with validation
- **Simple, reliable architecture** - Just works out of the box
## ⚡ Quick Start
```bash
pip install memorisdk
```
```python
from memori import Memori
# Create your workspace memory with conscious mode
office_work = Memori(
database_connect="sqlite:///office_memory.db",
conscious_ingest=True, # Short-term working memory (one-shot context)
openai_api_key="your-key"
)
office_work.enable() # Start recording conversations
# Use ANY LLM library - context automatically injected!
from litellm import completion
response = completion(
model="gpt-4o",
messages=[{"role": "user", "content": "Help me with Python testing"}]
)
# ✨ Short-term working memory automatically included once per session
```
## 🧠 How It Works
### 1. **Universal Recording**
```python
office_work.enable() # Records ALL LLM conversations automatically
```
### 2. **Intelligent Processing**
- **Entity Extraction**: Extracts people, technologies, projects
- **Smart Categorization**: Facts, preferences, skills, rules
- **Pydantic Validation**: Structured, type-safe memory storage
### 3. **Dual Memory Modes**
#### **🧠 Conscious Mode** - Short-Term Working Memory
```python
conscious_ingest=True # One-shot short-term memory injection
```
- **At Startup**: Conscious agent analyzes long-term memory patterns
- **Memory Promotion**: Moves essential conversations to short-term storage
- **One-Shot Injection**: Injects working memory once at conversation start
- **Like Human Short-Term Memory**: Names, current projects, preferences readily available
#### **🔍 Auto Mode** - Dynamic Database Search
```python
auto_ingest=True # Continuous intelligent memory retrieval
```
- **Every LLM Call**: Retrieval agent analyzes user query intelligently
- **Full Database Search**: Searches through entire memory database
- **Context-Aware**: Injects relevant memories based on current conversation
- **Performance Optimized**: Caching, async processing, background threads
## 🧠 Memory Modes Explained
### **Conscious Mode** - Short-Term Working Memory
```python
# Mimics human conscious memory - essential info readily available
memori = Memori(
database_connect="sqlite:///my_memory.db",
conscious_ingest=True, # 🧠 Short-term working memory
openai_api_key="sk-..."
)
```
**How Conscious Mode Works:**
1. **At Startup**: Conscious agent analyzes long-term memory patterns
2. **Essential Selection**: Promotes 5-10 most important conversations to short-term
3. **One-Shot Injection**: Injects this working memory once at conversation start
4. **No Repeats**: Won't inject again during the same session
### **Auto Mode** - Dynamic Intelligent Search
```python
# Searches entire database dynamically based on user queries
memori = Memori(
database_connect="sqlite:///my_memory.db",
auto_ingest=True, # 🔍 Smart database search
openai_api_key="sk-..."
)
```
**How Auto Mode Works:**
1. **Every LLM Call**: Retrieval agent analyzes user input
2. **Query Planning**: Uses AI to understand what memories are needed
3. **Smart Search**: Searches through entire database (short-term + long-term)
4. **Context Injection**: Injects 3-5 most relevant memories per call
### **Combined Mode** - Best of Both Worlds
```python
# Get both working memory AND dynamic search
memori = Memori(
conscious_ingest=True, # Working memory once
auto_ingest=True, # Dynamic search every call
openai_api_key="sk-..."
)
```
### **Intelligence Layers:**
1. **Memory Agent** - Processes every conversation with Pydantic structured outputs
2. **Conscious Agent** - Analyzes patterns, promotes long-term → short-term memories
3. **Retrieval Agent** - Intelligently searches and selects relevant context
### **What gets prioritized in Conscious Mode:**
- 👤 **Personal Identity**: Your name, role, location, basic info
- ❤️ **Preferences & Habits**: What you like, work patterns, routines
- 🛠️ **Skills & Tools**: Technologies you use, expertise areas
- 📊 **Current Projects**: Ongoing work, learning goals
- 🤝 **Relationships**: Important people, colleagues, connections
- 🔄 **Repeated References**: Information you mention frequently
## 🗄️ Memory Types
| Type | Purpose | Example | Auto-Promoted |
|------|---------|---------|---------------|
| **Facts** | Objective information | "I use PostgreSQL for databases" | ✅ High frequency |
| **Preferences** | User choices | "I prefer clean, readable code" | ✅ Personal identity |
| **Skills** | Abilities & knowledge | "Experienced with FastAPI" | ✅ Expertise areas |
| **Rules** | Constraints & guidelines | "Always write tests first" | ✅ Work patterns |
| **Context** | Session information | "Working on e-commerce project" | ✅ Current projects |
## 🔧 Configuration
### Simple Setup
```python
from memori import Memori
# Conscious mode - Short-term working memory
memori = Memori(
database_connect="sqlite:///my_memory.db",
template="basic",
conscious_ingest=True, # One-shot context injection
openai_api_key="sk-..."
)
# Auto mode - Dynamic database search
memori = Memori(
database_connect="sqlite:///my_memory.db",
auto_ingest=True, # Continuous memory retrieval
openai_api_key="sk-..."
)
# Combined mode - Best of both worlds
memori = Memori(
conscious_ingest=True, # Working memory +
auto_ingest=True, # Dynamic search
openai_api_key="sk-..."
)
```
### Advanced Configuration
```python
from memori import Memori, ConfigManager
# Load from memori.json or environment
config = ConfigManager()
config.auto_load()
memori = Memori()
memori.enable()
```
Create `memori.json`:
```json
{
"database": {
"connection_string": "postgresql://user:pass@localhost/memori"
},
"agents": {
"openai_api_key": "sk-...",
"conscious_ingest": true,
"auto_ingest": false
},
"memory": {
"namespace": "my_project",
"retention_policy": "30_days"
}
}
```
## 🔌 Universal Integration
Works with **ANY** LLM library:
```python
memori.enable() # Enable universal recording
# LiteLLM (recommended)
from litellm import completion
completion(model="gpt-4", messages=[...])
# OpenAI
import openai
client = openai.OpenAI()
client.chat.completions.create(...)
# Anthropic
import anthropic
client = anthropic.Anthropic()
client.messages.create(...)
# All automatically recorded and contextualized!
```
## 🛠️ Memory Management
### **Automatic Background Analysis**
```python
# Automatic analysis every 6 hours (when conscious_ingest=True)
memori.enable() # Starts background conscious agent
# Manual analysis trigger
memori.trigger_conscious_analysis()
# Get essential conversations
essential = memori.get_essential_conversations(limit=5)
```
### **Memory Retrieval Tools**
```python
from memori.tools import create_memory_tool
# Create memory search tool for your LLM
memory_tool = create_memory_tool(memori)
# Use in function calling
tools = [memory_tool]
completion(model="gpt-4", messages=[...], tools=tools)
```
### **Context Control**
```python
# Get relevant context for a query
context = memori.retrieve_context("Python testing", limit=5)
# Returns: 3 essential + 2 specific memories
# Search by category
skills = memori.search_memories_by_category("skill", limit=10)
# Get memory statistics
stats = memori.get_memory_stats()
```
## 📋 Database Schema
```sql
-- Core tables created automatically
chat_history # All conversations
short_term_memory # Recent context (expires)
long_term_memory # Permanent insights
rules_memory # User preferences
memory_entities # Extracted entities
memory_relationships # Entity connections
```
## 📁 Project Structure
```
memori/
├── core/ # Main Memori class, database manager
├── agents/ # Memory processing with Pydantic
├── database/ # SQLite/PostgreSQL/MySQL support
├── integrations/ # LiteLLM, OpenAI, Anthropic
├── config/ # Configuration management
├── utils/ # Helpers, validation, logging
└── tools/ # Memory search tools
```
## 🚀 Examples
- **[Basic Usage](./examples/basic_usage.py)** - Simple memory setup with conscious ingestion
- **[Personal Assistant](./examples/personal_assistant.py)** - AI assistant with intelligent memory
- **[Memory Retrieval](./memory_retrival_example.py)** - Function calling with memory tools
- **[Advanced Config](./examples/advanced_config.py)** - Production configuration
- **[Interactive Demo](./memori_example.py)** - Live conscious ingestion showcase
## 🤝 Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and guidelines.
## 📄 License
MIT License - see [LICENSE](./LICENSE) for details.
---
*Made for developers who want their AI agents to remember and learn*
Raw data
{
"_id": null,
"home_page": null,
"name": "memorisdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ai, memory, agents, llm, artificial-intelligence, multi-agent",
"author": null,
"author_email": "Memori Team <contact@memori.dev>",
"download_url": "https://files.pythonhosted.org/packages/60/de/ba5c2f8d0d9816707796e84eecdbe18e6686c906e6228f004f7ba00030fe/memorisdk-1.0.1.tar.gz",
"platform": null,
"description": "# Memori\n\n**The Open-Source Memory Layer for AI Agents & Multi-Agent Systems v1.2**\n\n*Give your AI agents structured, persistent memory with intelligent context injection - no more repeating yourself!*\n\n[](https://badge.fury.io/py/memori)\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n\n---\n\n## \ud83c\udfaf Philosophy\n\n- **Second-memory for all your LLM work** - Never repeat context again\n- **Dual-mode memory injection** - Conscious short-term memory + Auto intelligent search\n- **Flexible database connections** - SQLite, PostgreSQL, MySQL support \n- **Pydantic-based intelligence** - Structured memory processing with validation\n- **Simple, reliable architecture** - Just works out of the box\n\n## \u26a1 Quick Start\n\n```bash\npip install memorisdk\n```\n\n```python\nfrom memori import Memori\n\n# Create your workspace memory with conscious mode\noffice_work = Memori(\n database_connect=\"sqlite:///office_memory.db\",\n conscious_ingest=True, # Short-term working memory (one-shot context)\n openai_api_key=\"your-key\"\n)\n\noffice_work.enable() # Start recording conversations\n\n# Use ANY LLM library - context automatically injected!\nfrom litellm import completion\n\nresponse = completion(\n model=\"gpt-4o\", \n messages=[{\"role\": \"user\", \"content\": \"Help me with Python testing\"}]\n)\n# \u2728 Short-term working memory automatically included once per session\n```\n\n## \ud83e\udde0 How It Works\n\n### 1. **Universal Recording**\n```python\noffice_work.enable() # Records ALL LLM conversations automatically\n```\n\n### 2. **Intelligent Processing**\n- **Entity Extraction**: Extracts people, technologies, projects\n- **Smart Categorization**: Facts, preferences, skills, rules\n- **Pydantic Validation**: Structured, type-safe memory storage\n\n### 3. **Dual Memory Modes**\n\n#### **\ud83e\udde0 Conscious Mode** - Short-Term Working Memory\n```python\nconscious_ingest=True # One-shot short-term memory injection\n```\n- **At Startup**: Conscious agent analyzes long-term memory patterns\n- **Memory Promotion**: Moves essential conversations to short-term storage\n- **One-Shot Injection**: Injects working memory once at conversation start\n- **Like Human Short-Term Memory**: Names, current projects, preferences readily available\n\n#### **\ud83d\udd0d Auto Mode** - Dynamic Database Search\n```python\nauto_ingest=True # Continuous intelligent memory retrieval\n```\n- **Every LLM Call**: Retrieval agent analyzes user query intelligently\n- **Full Database Search**: Searches through entire memory database\n- **Context-Aware**: Injects relevant memories based on current conversation\n- **Performance Optimized**: Caching, async processing, background threads\n\n## \ud83e\udde0 Memory Modes Explained\n\n### **Conscious Mode** - Short-Term Working Memory\n```python\n# Mimics human conscious memory - essential info readily available\nmemori = Memori(\n database_connect=\"sqlite:///my_memory.db\",\n conscious_ingest=True, # \ud83e\udde0 Short-term working memory\n openai_api_key=\"sk-...\"\n)\n```\n\n**How Conscious Mode Works:**\n1. **At Startup**: Conscious agent analyzes long-term memory patterns\n2. **Essential Selection**: Promotes 5-10 most important conversations to short-term\n3. **One-Shot Injection**: Injects this working memory once at conversation start\n4. **No Repeats**: Won't inject again during the same session\n\n### **Auto Mode** - Dynamic Intelligent Search\n```python\n# Searches entire database dynamically based on user queries\nmemori = Memori(\n database_connect=\"sqlite:///my_memory.db\", \n auto_ingest=True, # \ud83d\udd0d Smart database search\n openai_api_key=\"sk-...\"\n)\n```\n\n**How Auto Mode Works:**\n1. **Every LLM Call**: Retrieval agent analyzes user input\n2. **Query Planning**: Uses AI to understand what memories are needed\n3. **Smart Search**: Searches through entire database (short-term + long-term)\n4. **Context Injection**: Injects 3-5 most relevant memories per call\n\n### **Combined Mode** - Best of Both Worlds\n```python\n# Get both working memory AND dynamic search\nmemori = Memori(\n conscious_ingest=True, # Working memory once\n auto_ingest=True, # Dynamic search every call\n openai_api_key=\"sk-...\"\n)\n```\n\n### **Intelligence Layers:**\n\n1. **Memory Agent** - Processes every conversation with Pydantic structured outputs\n2. **Conscious Agent** - Analyzes patterns, promotes long-term \u2192 short-term memories\n3. **Retrieval Agent** - Intelligently searches and selects relevant context\n\n### **What gets prioritized in Conscious Mode:**\n- \ud83d\udc64 **Personal Identity**: Your name, role, location, basic info\n- \u2764\ufe0f **Preferences & Habits**: What you like, work patterns, routines\n- \ud83d\udee0\ufe0f **Skills & Tools**: Technologies you use, expertise areas\n- \ud83d\udcca **Current Projects**: Ongoing work, learning goals\n- \ud83e\udd1d **Relationships**: Important people, colleagues, connections\n- \ud83d\udd04 **Repeated References**: Information you mention frequently\n\n## \ud83d\uddc4\ufe0f Memory Types\n\n| Type | Purpose | Example | Auto-Promoted |\n|------|---------|---------|---------------|\n| **Facts** | Objective information | \"I use PostgreSQL for databases\" | \u2705 High frequency |\n| **Preferences** | User choices | \"I prefer clean, readable code\" | \u2705 Personal identity |\n| **Skills** | Abilities & knowledge | \"Experienced with FastAPI\" | \u2705 Expertise areas |\n| **Rules** | Constraints & guidelines | \"Always write tests first\" | \u2705 Work patterns |\n| **Context** | Session information | \"Working on e-commerce project\" | \u2705 Current projects |\n\n## \ud83d\udd27 Configuration\n\n### Simple Setup\n```python\nfrom memori import Memori\n\n# Conscious mode - Short-term working memory\nmemori = Memori(\n database_connect=\"sqlite:///my_memory.db\",\n template=\"basic\", \n conscious_ingest=True, # One-shot context injection\n openai_api_key=\"sk-...\"\n)\n\n# Auto mode - Dynamic database search\nmemori = Memori(\n database_connect=\"sqlite:///my_memory.db\",\n auto_ingest=True, # Continuous memory retrieval\n openai_api_key=\"sk-...\"\n)\n\n# Combined mode - Best of both worlds\nmemori = Memori(\n conscious_ingest=True, # Working memory + \n auto_ingest=True, # Dynamic search\n openai_api_key=\"sk-...\"\n)\n```\n\n### Advanced Configuration\n```python\nfrom memori import Memori, ConfigManager\n\n# Load from memori.json or environment\nconfig = ConfigManager()\nconfig.auto_load()\n\nmemori = Memori()\nmemori.enable()\n```\n\nCreate `memori.json`:\n```json\n{\n \"database\": {\n \"connection_string\": \"postgresql://user:pass@localhost/memori\"\n },\n \"agents\": {\n \"openai_api_key\": \"sk-...\",\n \"conscious_ingest\": true,\n \"auto_ingest\": false\n },\n \"memory\": {\n \"namespace\": \"my_project\",\n \"retention_policy\": \"30_days\"\n }\n}\n```\n\n## \ud83d\udd0c Universal Integration\n\nWorks with **ANY** LLM library:\n\n```python\nmemori.enable() # Enable universal recording\n\n# LiteLLM (recommended)\nfrom litellm import completion\ncompletion(model=\"gpt-4\", messages=[...])\n\n# OpenAI\nimport openai\nclient = openai.OpenAI()\nclient.chat.completions.create(...)\n\n# Anthropic \nimport anthropic\nclient = anthropic.Anthropic()\nclient.messages.create(...)\n\n# All automatically recorded and contextualized!\n```\n\n## \ud83d\udee0\ufe0f Memory Management\n\n### **Automatic Background Analysis**\n```python\n# Automatic analysis every 6 hours (when conscious_ingest=True)\nmemori.enable() # Starts background conscious agent\n\n# Manual analysis trigger\nmemori.trigger_conscious_analysis()\n\n# Get essential conversations\nessential = memori.get_essential_conversations(limit=5)\n```\n\n### **Memory Retrieval Tools**\n```python\nfrom memori.tools import create_memory_tool\n\n# Create memory search tool for your LLM\nmemory_tool = create_memory_tool(memori)\n\n# Use in function calling\ntools = [memory_tool]\ncompletion(model=\"gpt-4\", messages=[...], tools=tools)\n```\n\n### **Context Control**\n```python\n# Get relevant context for a query\ncontext = memori.retrieve_context(\"Python testing\", limit=5)\n# Returns: 3 essential + 2 specific memories\n\n# Search by category\nskills = memori.search_memories_by_category(\"skill\", limit=10)\n\n# Get memory statistics\nstats = memori.get_memory_stats()\n```\n\n## \ud83d\udccb Database Schema\n\n```sql\n-- Core tables created automatically\nchat_history # All conversations\nshort_term_memory # Recent context (expires)\nlong_term_memory # Permanent insights \nrules_memory # User preferences\nmemory_entities # Extracted entities\nmemory_relationships # Entity connections\n```\n\n## \ud83d\udcc1 Project Structure\n\n```\nmemori/\n\u251c\u2500\u2500 core/ # Main Memori class, database manager\n\u251c\u2500\u2500 agents/ # Memory processing with Pydantic \n\u251c\u2500\u2500 database/ # SQLite/PostgreSQL/MySQL support\n\u251c\u2500\u2500 integrations/ # LiteLLM, OpenAI, Anthropic\n\u251c\u2500\u2500 config/ # Configuration management\n\u251c\u2500\u2500 utils/ # Helpers, validation, logging\n\u2514\u2500\u2500 tools/ # Memory search tools\n```\n\n## \ud83d\ude80 Examples\n\n- **[Basic Usage](./examples/basic_usage.py)** - Simple memory setup with conscious ingestion\n- **[Personal Assistant](./examples/personal_assistant.py)** - AI assistant with intelligent memory\n- **[Memory Retrieval](./memory_retrival_example.py)** - Function calling with memory tools\n- **[Advanced Config](./examples/advanced_config.py)** - Production configuration\n- **[Interactive Demo](./memori_example.py)** - Live conscious ingestion showcase\n\n## \ud83e\udd1d Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and guidelines.\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](./LICENSE) for details.\n\n---\n\n*Made for developers who want their AI agents to remember and learn*\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "The Open-Source Memory Layer for AI Agents & Multi-Agent Systems",
"version": "1.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/GibsonAI/memori/issues",
"Changelog": "https://github.com/GibsonAI/memori/blob/main/CHANGELOG.md",
"Contributing": "https://github.com/GibsonAI/memori/blob/main/CONTRIBUTING.md",
"Documentation": "https://gibsonai.github.io/memori",
"Homepage": "https://github.com/GibsonAI/memori",
"Repository": "https://github.com/GibsonAI/memori.git"
},
"split_keywords": [
"ai",
" memory",
" agents",
" llm",
" artificial-intelligence",
" multi-agent"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4b4baf27c1b2f5e86a27d13eedacdea46c28dc91e5d45951dbe5beb8987a6fbb",
"md5": "4817a24270e8415f31884ba1713810b1",
"sha256": "596db13afa44c3f018b8fea32a00f0742452895e8a26d6473d9d3ae0bc602385"
},
"downloads": -1,
"filename": "memorisdk-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4817a24270e8415f31884ba1713810b1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 84573,
"upload_time": "2025-08-04T08:53:11",
"upload_time_iso_8601": "2025-08-04T08:53:11.251609Z",
"url": "https://files.pythonhosted.org/packages/4b/4b/af27c1b2f5e86a27d13eedacdea46c28dc91e5d45951dbe5beb8987a6fbb/memorisdk-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "60deba5c2f8d0d9816707796e84eecdbe18e6686c906e6228f004f7ba00030fe",
"md5": "5f9c7918023a801b6866f4d733fc863f",
"sha256": "80cdcbe1f6ae5f40d0fa8c3903ea0aa06bf8238a936764412ea7c65156a6ffee"
},
"downloads": -1,
"filename": "memorisdk-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "5f9c7918023a801b6866f4d733fc863f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 74952,
"upload_time": "2025-08-04T08:53:12",
"upload_time_iso_8601": "2025-08-04T08:53:12.959981Z",
"url": "https://files.pythonhosted.org/packages/60/de/ba5c2f8d0d9816707796e84eecdbe18e6686c906e6228f004f7ba00030fe/memorisdk-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 08:53:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "GibsonAI",
"github_project": "memori",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "loguru",
"specs": [
[
">=",
"0.6.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
}
],
"lcname": "memorisdk"
}
JSON
