# SmartMemory - Multi-Layered AI Memory System
[](https://pypi.org/project/smartmemory/)
[](https://www.gnu.org/licenses/agpl-3.0)
[](https://www.python.org/downloads/)
SmartMemory is a comprehensive AI memory system that provides persistent, multi-layered memory storage and retrieval for AI applications. It combines graph databases, vector stores, and intelligent processing pipelines to create a unified memory architecture.
## 🚀 Quick Install
```bash
pip install smartmemory
```
## Architecture Overview
SmartMemory implements a multi-layered memory architecture with the following components:
### Core Components
- **SmartMemory**: Main unified memory interface (`smartmemory.smart_memory.SmartMemory`)
- **SmartGraph**: Graph database backend using FalkorDB for relationship storage
- **Memory Types**: Specialized memory stores for different data types
- **Pipeline Stages**: Processing stages for ingestion, enrichment, and evolution
- **Plugin System**: Extensible architecture for custom evolvers and enrichers
### Memory Types
- **Working Memory**: Short-term context buffer (in-memory, capacity=10)
- **Semantic Memory**: Facts and concepts with vector embeddings
- **Episodic Memory**: Personal experiences and learning history
- **Procedural Memory**: Skills, strategies, and learned patterns
- **Zettelkasten Memory**: Bidirectional note-taking system with AI-powered knowledge discovery
### Storage Backend
- **FalkorDB**: Graph database for relationships and vector storage
- **Redis**: Caching layer for performance optimization
### Processing Pipeline
The memory ingestion flow processes data through several stages:
1. **Input Adaptation**: Convert input data to MemoryItem format
2. **Classification**: Determine appropriate memory type
3. **Extraction**: Extract entities and relationships
4. **Storage**: Persist to appropriate memory stores
5. **Linking**: Create connections between related memories
6. **Enrichment**: Enhance memories with additional context
7. **Evolution**: Transform memories based on configured rules
## Key Features
- **Multi-Type Memory System**: Working, Semantic, Episodic, and Procedural memory types
- **Graph-Based Storage**: FalkorDB backend for complex relationship modeling
- **Vector Similarity**: FalkorDB vector storage for semantic search
- **Extensible Pipeline**: Modular processing stages for ingestion and evolution
- **Plugin Architecture**: 18 built-in plugins with external plugin support
- **Plugin Security**: Sandboxing, permissions, and resource limits for safe plugin execution
- **Multi-User Support**: User and group isolation for enterprise applications
- **Caching Layer**: Redis-based performance optimization
- **Configuration Management**: Flexible configuration with environment variable support
## 📦 Installation
### From PyPI (Recommended)
```bash
# Core package
pip install smartmemory
# With optional features
pip install smartmemory[cli] # CLI tools
pip install smartmemory[rebel] # REBEL relation extractor
pip install smartmemory[relik] # ReliK relation extractor
pip install smartmemory[wikipedia] # Wikipedia enrichment
pip install smartmemory[all] # All optional features
```
### From Source (Development)
```bash
git clone https://github.com/smart-memory/smart-memory.git
cd smart-memory
pip install -e ".[dev]"
# Install spaCy model for entity extraction
python -m spacy download en_core_web_sm
```
### Docker Deployment
See the [smart-memory-service](https://github.com/smart-memory/smart-memory-service) repository for production-ready Docker deployment with FastAPI, authentication, and multi-tenancy support.
## 🎯 Quick Start
### Basic Usage
```python
from smartmemory import SmartMemory, MemoryItem
# Initialize SmartMemory
memory = SmartMemory()
# Add a memory
item = MemoryItem(
content="User prefers Python for data analysis tasks",
memory_type="semantic",
user_id="user123",
metadata={'topic': 'preferences', 'domain': 'programming'}
)
memory.add(item)
# Search memories
results = memory.search("Python programming", top_k=5)
for result in results:
print(f"Content: {result.content}")
print(f"Type: {result.memory_type}")
# Get memory summary
summary = memory.summary()
print(f"Total memories: {summary}")
```
### Using Different Memory Types
```python
from smartmemory import SmartMemory, MemoryItem
# Initialize SmartMemory
memory = SmartMemory()
# Add working memory (short-term context)
working_item = MemoryItem(
content="Current conversation context",
memory_type="working"
)
memory.add(working_item)
# Add semantic memory (facts and concepts)
semantic_item = MemoryItem(
content="Python is a high-level programming language",
memory_type="semantic"
)
memory.add(semantic_item)
# Add episodic memory (experiences)
episodic_item = MemoryItem(
content="User completed Python tutorial on 2024-01-15",
memory_type="episodic"
)
memory.add(episodic_item)
# Add procedural memory (skills and procedures)
procedural_item = MemoryItem(
content="To sort a list in Python: use list.sort() or sorted(list)",
memory_type="procedural"
)
memory.add(procedural_item)
# Add Zettelkasten note (interconnected knowledge)
zettel_item = MemoryItem(
content="# Machine Learning\n\nML learns from data using algorithms.",
memory_type="zettel",
metadata={'title': 'ML Basics', 'tags': ['ai', 'ml']}
)
memory.add(zettel_item)
```
### CLI Usage (Optional)
```bash
# Install CLI tools
pip install smartmemory[cli]
# Show system info
smartmemory info
# List all plugins
smartmemory plugins list
# Get plugin details
smartmemory plugins info llm
# Add a memory
smartmemory add "Python is great for AI" --memory-type semantic
# Search memories
smartmemory search "Python programming" --top-k 5
# Show summary
smartmemory summary
```
## Use Cases
### Conversational AI Systems
- Maintain context across multiple conversation sessions
- Learn user preferences and adapt responses
- Build comprehensive user profiles over time
### Educational Applications
- Track learning progress and adapt teaching strategies
- Remember previous topics and build upon them
- Personalize content based on individual learning patterns
### Knowledge Management
- Store and retrieve complex information relationships
- Connect related concepts across different domains
- Evolve understanding through continuous learning
- Build a personal knowledge base with Zettelkasten method
### Personal AI Assistants
- Remember user preferences and past interactions
- Provide contextually relevant recommendations
- Learn from user feedback to improve responses
## Examples
The `examples/` directory contains several demonstration scripts:
- `memory_system_usage_example.py`: Basic memory operations (add, search, delete)
- `zettelkasten_example.py`: Complete Zettelkasten system demonstration
- `conversational_assistant_example.py`: Conversational AI with memory
- `advanced_programming_tutor.py`: Educational application example
- `working_holistic_example.py`: Comprehensive multi-session demo
- `background_processing_demo.py`: Asynchronous processing example
## Configuration
SmartMemory uses environment variables for configuration:
### Environment Variables
Key environment variables:
- `FALKORDB_HOST`: FalkorDB server host (default: localhost)
- `FALKORDB_PORT`: FalkorDB server port (default: 6379)
- `REDIS_HOST`: Redis server host (default: localhost)
- `REDIS_PORT`: Redis server port (default: 6379)
- `OPENAI_API_KEY`: OpenAI API key for embeddings
```bash
# Example .env file
export FALKORDB_HOST=localhost
export FALKORDB_PORT=6379
export REDIS_HOST=localhost
export REDIS_PORT=6379
export OPENAI_API_KEY=your-api-key-here
```
## Memory Evolution
SmartMemory includes built-in evolvers that automatically transform memories:
### Available Evolvers
- **WorkingToEpisodicEvolver**: Converts working memory to episodic when buffer is full
- **WorkingToProceduralEvolver**: Extracts repeated patterns as procedures
- **EpisodicToSemanticEvolver**: Promotes stable facts to semantic memory
- **EpisodicToZettelEvolver**: Converts episodic events to Zettelkasten notes
- **EpisodicDecayEvolver**: Archives old episodic memories
- **SemanticDecayEvolver**: Prunes low-relevance semantic facts
- **ZettelPruneEvolver**: Merges duplicate or low-quality notes
Evolvers run automatically as part of the memory lifecycle. See the [examples](examples/) directory for evolution demonstrations.
## Plugin System
SmartMemory features a **unified, extensible plugin architecture** that allows you to customize and extend functionality. All plugins follow a consistent class-based pattern.
### Built-in Plugins
SmartMemory includes **18 built-in plugins** across 4 types:
- **4 Extractors**: Extract entities and relationships
- `SpacyExtractor`, `LLMExtractor`, `RebelExtractor`, `RelikExtractor`
- **6 Enrichers**: Add context and metadata to memories
- `BasicEnricher`, `SentimentEnricher`, `TemporalEnricher`, `TopicEnricher`, `SkillsToolsEnricher`, `WikipediaEnricher`
- **1 Grounder**: Connect to external knowledge
- `WikipediaGrounder`
- **7 Evolvers**: Transform memories based on rules
- `WorkingToEpisodicEvolver`, `EpisodicToSemanticEvolver`, `SemanticDecayEvolver`, etc.
### Creating Custom Plugins
Create your own plugins by extending the base classes:
```python
from smartmemory.plugins.base import EnricherPlugin, PluginMetadata
class MyCustomEnricher(EnricherPlugin):
@classmethod
def metadata(cls):
return PluginMetadata(
name="my_enricher",
version="1.0.0",
author="Your Name",
description="My custom enricher",
plugin_type="enricher",
dependencies=["some-lib>=1.0.0"],
security_profile="standard",
requires_network=False,
requires_llm=False
)
def enrich(self, item, node_ids=None):
# Your enrichment logic
item.metadata["custom_field"] = "value"
return item.metadata
```
See the [examples](examples/) directory for complete plugin examples.
### Publishing Plugins
Publish your plugin as a Python package with entry points:
```toml
# pyproject.toml
[project.entry-points."smartmemory.plugins.enrichers"]
my_enricher = "my_package:MyCustomEnricher"
```
Install and use:
```bash
pip install my-smartmemory-plugin
# Automatically discovered and loaded!
```
### Plugin Types
- **ExtractorPlugin**: Extract entities and relationships from text
- **EnricherPlugin**: Add metadata and context to memories
- **GrounderPlugin**: Link memories to external knowledge sources
- **EvolverPlugin**: Transform memories based on conditions
All plugins are automatically discovered and registered at startup.
### Plugin Security
SmartMemory includes a comprehensive security system for plugins:
- **4 Security Profiles**: `trusted`, `standard` (default), `restricted`, `untrusted`
- **Permission System**: Control memory, network, file, and LLM access
- **Resource Limits**: Automatic timeout (30s), memory limits, network request limits
- **Sandboxing**: Isolated execution with security enforcement
- **Static Validation**: Detects security issues before execution
```python
# Plugins are secure by default
PluginMetadata(
security_profile="standard", # Balanced security
requires_network=True, # Explicitly declare requirements
requires_llm=False
)
```
See `docs/PLUGIN_SECURITY.md` for complete security documentation.
### Examples
See the `examples/` directory for complete plugin examples:
- `custom_enricher_example.py` - Sentiment analysis and keyword extraction
- `custom_evolver_example.py` - Memory promotion and archival
- `custom_extractor_example.py` - Regex and domain-specific NER
- `custom_grounder_example.py` - DBpedia and custom API grounding
## Testing
Run the test suite:
```bash
# Run all tests
PYTHONPATH=. pytest -v tests/
# Run specific test categories
PYTHONPATH=. pytest tests/unit/
PYTHONPATH=. pytest tests/integration/
PYTHONPATH=. pytest tests/e2e/
# Run examples
PYTHONPATH=. python examples/memory_system_usage_example.py
PYTHONPATH=. python examples/conversational_assistant_example.py
```
## API Reference
### SmartMemory Class
Main interface for memory operations:
```python
class SmartMemory:
def add(self, item: MemoryItem) -> Optional[MemoryItem]
def get(self, item_id: str) -> Optional[MemoryItem]
def search(self, query: str, top_k: int = 10) -> List[MemoryItem]
def delete(self, item_id: str) -> bool
def clear(self) -> None
def summary(self) -> Dict[str, Any]
def ingest(self, content: str, **kwargs) -> MemoryItem
```
### MemoryItem Class
Core data structure for memory storage:
```python
@dataclass
class MemoryItem:
content: str
memory_type: str = 'semantic'
item_id: str = field(default_factory=lambda: str(uuid.uuid4()))
user_id: Optional[str] = None
group_id: Optional[str] = None
valid_start_time: Optional[datetime] = None
valid_end_time: Optional[datetime] = None
transaction_time: datetime = field(default_factory=datetime.now)
embedding: Optional[List[float]] = None
entities: Optional[list] = None
relations: Optional[list] = None
metadata: dict = field(default_factory=dict)
```
## Dependencies
### Core Dependencies
SmartMemory requires the following key dependencies:
- `falkordb`: Graph database and vector storage backend
- `spacy`: Natural language processing and entity extraction
- `litellm`: LLM integration layer
- `openai`: OpenAI API client (for embeddings)
- `redis`: Caching layer
- `scikit-learn`: Machine learning utilities
- `pydantic`: Data validation
- `python-dateutil`: Date/time handling
- `vaderSentiment`: Sentiment analysis
- `jinja2`: Template rendering
**Note:** SmartMemory uses FalkorDB for both graph and vector storage. While the codebase contains legacy ChromaDB integration code, FalkorDB is the primary and recommended backend.
### Optional Dependencies
Install additional features as needed:
```bash
# Specific extractors
pip install smartmemory[rebel] # REBEL relation extraction
pip install smartmemory[relik] # ReliK relation extraction
# Integrations
pip install smartmemory[slack] # Slack integration
pip install smartmemory[aws] # AWS integration
pip install smartmemory[wikipedia] # Wikipedia enrichment
# Tools
pip install smartmemory[cli] # Command-line interface
# Everything
pip install smartmemory[all] # All optional features
```
## Contributing
Contributions are welcome! Please follow these guidelines:
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request
For major changes, please open an issue first to discuss the proposed changes.
## 📄 License
SmartMemory is dual-licensed to provide flexibility for both open-source and commercial use. See [LICENSE](LICENSE) for details.
## Security
SmartMemory takes plugin security seriously. All plugins run in a sandboxed environment with:
- ✅ **Permission checks** - Plugins must declare what they access
- ✅ **Resource limits** - Automatic timeouts and memory limits
- ✅ **Execution isolation** - Sandboxed plugin execution
- ✅ **Static analysis** - Security validation before execution
External plugins use the `standard` security profile by default. See `docs/PLUGIN_SECURITY.md` for details.
## 🔗 Links
- **📦 PyPI Package**: https://pypi.org/project/smartmemory/
- **📚 Documentation**: https://docs.smartmemory.ai
- **🐙 GitHub Repository**: https://github.com/smart-memory/smart-memory
- **🐛 Issue Tracker**: https://github.com/smart-memory/smart-memory/issues
- **🔒 Security Policy**: See `docs/PLUGIN_SECURITY.md`
- **🚀 Production Service**: https://github.com/smart-memory/smart-memory-service
---
**Get started with SmartMemory today!**
```bash
pip install smartmemory
```
Explore the [examples](examples/) directory for complete demonstrations and use cases.
---
## 🚧 In Progress
The following features are currently under active development:
### Ontology System
- **Current**: Basic concept and relation extraction
- **In Progress**:
- Ontology governance and validation
- External ontology integration (DBpedia, Schema.org)
- Semantic clustering and concept hierarchies
- Ontology-driven query expansion
- **Planned**: Full ontology management with Maya integration
### Temporal Queries
- **Current**: Basic bi-temporal support (valid_time, transaction_time)
- **In Progress**:
- Time-travel queries
- Version history tracking
- Audit trail generation
- **Planned**: Advanced temporal analytics
### Multi-Tenancy (Service Layer)
- **Current**: Single-user mode
- **In Progress**: Full multi-tenancy support in smart-memory-service
- **Planned**: Team collaboration features
These features are functional but not yet production-ready. Check the [GitHub repository](https://github.com/smart-memory/smart-memory) for the latest updates.
Raw data
{
"_id": null,
"home_page": null,
"name": "smartmemory",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, memory, graph-database, vector-database, llm, knowledge-graph, semantic-memory, episodic-memory, rag, embeddings",
"author": "SmartMemory Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/2f/e8/2775d8ae1a33a5a61113027bec413a077d17a353f90e0ac14acc7bf196ed/smartmemory-0.1.11.tar.gz",
"platform": null,
"description": "# SmartMemory - Multi-Layered AI Memory System\n\n[](https://pypi.org/project/smartmemory/)\n[](https://www.gnu.org/licenses/agpl-3.0)\n[](https://www.python.org/downloads/)\n\nSmartMemory is a comprehensive AI memory system that provides persistent, multi-layered memory storage and retrieval for AI applications. It combines graph databases, vector stores, and intelligent processing pipelines to create a unified memory architecture.\n\n## \ud83d\ude80 Quick Install\n\n```bash\npip install smartmemory\n```\n\n## Architecture Overview\n\nSmartMemory implements a multi-layered memory architecture with the following components:\n\n### Core Components\n\n- **SmartMemory**: Main unified memory interface (`smartmemory.smart_memory.SmartMemory`)\n- **SmartGraph**: Graph database backend using FalkorDB for relationship storage\n- **Memory Types**: Specialized memory stores for different data types\n- **Pipeline Stages**: Processing stages for ingestion, enrichment, and evolution\n- **Plugin System**: Extensible architecture for custom evolvers and enrichers\n\n### Memory Types\n\n- **Working Memory**: Short-term context buffer (in-memory, capacity=10)\n- **Semantic Memory**: Facts and concepts with vector embeddings\n- **Episodic Memory**: Personal experiences and learning history\n- **Procedural Memory**: Skills, strategies, and learned patterns\n- **Zettelkasten Memory**: Bidirectional note-taking system with AI-powered knowledge discovery\n\n### Storage Backend\n\n- **FalkorDB**: Graph database for relationships and vector storage\n- **Redis**: Caching layer for performance optimization\n\n### Processing Pipeline\n\nThe memory ingestion flow processes data through several stages:\n\n1. **Input Adaptation**: Convert input data to MemoryItem format\n2. **Classification**: Determine appropriate memory type\n3. **Extraction**: Extract entities and relationships\n4. **Storage**: Persist to appropriate memory stores\n5. **Linking**: Create connections between related memories\n6. **Enrichment**: Enhance memories with additional context\n7. **Evolution**: Transform memories based on configured rules\n\n## Key Features\n\n- **Multi-Type Memory System**: Working, Semantic, Episodic, and Procedural memory types\n- **Graph-Based Storage**: FalkorDB backend for complex relationship modeling\n- **Vector Similarity**: FalkorDB vector storage for semantic search\n- **Extensible Pipeline**: Modular processing stages for ingestion and evolution\n- **Plugin Architecture**: 18 built-in plugins with external plugin support\n- **Plugin Security**: Sandboxing, permissions, and resource limits for safe plugin execution\n- **Multi-User Support**: User and group isolation for enterprise applications\n- **Caching Layer**: Redis-based performance optimization\n- **Configuration Management**: Flexible configuration with environment variable support\n\n## \ud83d\udce6 Installation\n\n### From PyPI (Recommended)\n\n```bash\n# Core package\npip install smartmemory\n\n# With optional features\npip install smartmemory[cli] # CLI tools\npip install smartmemory[rebel] # REBEL relation extractor\npip install smartmemory[relik] # ReliK relation extractor\npip install smartmemory[wikipedia] # Wikipedia enrichment\npip install smartmemory[all] # All optional features\n```\n\n### From Source (Development)\n\n```bash\ngit clone https://github.com/smart-memory/smart-memory.git\ncd smart-memory\npip install -e \".[dev]\"\n\n# Install spaCy model for entity extraction\npython -m spacy download en_core_web_sm\n```\n\n### Docker Deployment\n\nSee the [smart-memory-service](https://github.com/smart-memory/smart-memory-service) repository for production-ready Docker deployment with FastAPI, authentication, and multi-tenancy support.\n\n## \ud83c\udfaf Quick Start\n\n### Basic Usage\n\n```python\nfrom smartmemory import SmartMemory, MemoryItem\n\n# Initialize SmartMemory\nmemory = SmartMemory()\n\n# Add a memory\nitem = MemoryItem(\n content=\"User prefers Python for data analysis tasks\",\n memory_type=\"semantic\",\n user_id=\"user123\",\n metadata={'topic': 'preferences', 'domain': 'programming'}\n)\nmemory.add(item)\n\n# Search memories\nresults = memory.search(\"Python programming\", top_k=5)\nfor result in results:\n print(f\"Content: {result.content}\")\n print(f\"Type: {result.memory_type}\")\n\n# Get memory summary\nsummary = memory.summary()\nprint(f\"Total memories: {summary}\")\n```\n\n### Using Different Memory Types\n\n```python\nfrom smartmemory import SmartMemory, MemoryItem\n\n# Initialize SmartMemory\nmemory = SmartMemory()\n\n# Add working memory (short-term context)\nworking_item = MemoryItem(\n content=\"Current conversation context\",\n memory_type=\"working\"\n)\nmemory.add(working_item)\n\n# Add semantic memory (facts and concepts)\nsemantic_item = MemoryItem(\n content=\"Python is a high-level programming language\",\n memory_type=\"semantic\"\n)\nmemory.add(semantic_item)\n\n# Add episodic memory (experiences)\nepisodic_item = MemoryItem(\n content=\"User completed Python tutorial on 2024-01-15\",\n memory_type=\"episodic\"\n)\nmemory.add(episodic_item)\n\n# Add procedural memory (skills and procedures)\nprocedural_item = MemoryItem(\n content=\"To sort a list in Python: use list.sort() or sorted(list)\",\n memory_type=\"procedural\"\n)\nmemory.add(procedural_item)\n\n# Add Zettelkasten note (interconnected knowledge)\nzettel_item = MemoryItem(\n content=\"# Machine Learning\\n\\nML learns from data using algorithms.\",\n memory_type=\"zettel\",\n metadata={'title': 'ML Basics', 'tags': ['ai', 'ml']}\n)\nmemory.add(zettel_item)\n```\n\n### CLI Usage (Optional)\n\n```bash\n# Install CLI tools\npip install smartmemory[cli]\n\n# Show system info\nsmartmemory info\n\n# List all plugins\nsmartmemory plugins list\n\n# Get plugin details\nsmartmemory plugins info llm\n\n# Add a memory\nsmartmemory add \"Python is great for AI\" --memory-type semantic\n\n# Search memories\nsmartmemory search \"Python programming\" --top-k 5\n\n# Show summary\nsmartmemory summary\n```\n\n## Use Cases\n\n### Conversational AI Systems\n- Maintain context across multiple conversation sessions\n- Learn user preferences and adapt responses\n- Build comprehensive user profiles over time\n\n### Educational Applications\n- Track learning progress and adapt teaching strategies\n- Remember previous topics and build upon them\n- Personalize content based on individual learning patterns\n\n### Knowledge Management\n- Store and retrieve complex information relationships\n- Connect related concepts across different domains\n- Evolve understanding through continuous learning\n- Build a personal knowledge base with Zettelkasten method\n\n### Personal AI Assistants\n- Remember user preferences and past interactions\n- Provide contextually relevant recommendations\n- Learn from user feedback to improve responses\n\n## Examples\n\nThe `examples/` directory contains several demonstration scripts:\n\n- `memory_system_usage_example.py`: Basic memory operations (add, search, delete)\n- `zettelkasten_example.py`: Complete Zettelkasten system demonstration\n- `conversational_assistant_example.py`: Conversational AI with memory\n- `advanced_programming_tutor.py`: Educational application example\n- `working_holistic_example.py`: Comprehensive multi-session demo\n- `background_processing_demo.py`: Asynchronous processing example\n\n## Configuration\n\nSmartMemory uses environment variables for configuration:\n\n### Environment Variables\n\nKey environment variables:\n- `FALKORDB_HOST`: FalkorDB server host (default: localhost)\n- `FALKORDB_PORT`: FalkorDB server port (default: 6379)\n- `REDIS_HOST`: Redis server host (default: localhost)\n- `REDIS_PORT`: Redis server port (default: 6379)\n- `OPENAI_API_KEY`: OpenAI API key for embeddings\n\n```bash\n# Example .env file\nexport FALKORDB_HOST=localhost\nexport FALKORDB_PORT=6379\nexport REDIS_HOST=localhost\nexport REDIS_PORT=6379\nexport OPENAI_API_KEY=your-api-key-here\n```\n\n## Memory Evolution\n\nSmartMemory includes built-in evolvers that automatically transform memories:\n\n### Available Evolvers\n\n- **WorkingToEpisodicEvolver**: Converts working memory to episodic when buffer is full\n- **WorkingToProceduralEvolver**: Extracts repeated patterns as procedures\n- **EpisodicToSemanticEvolver**: Promotes stable facts to semantic memory\n- **EpisodicToZettelEvolver**: Converts episodic events to Zettelkasten notes\n- **EpisodicDecayEvolver**: Archives old episodic memories\n- **SemanticDecayEvolver**: Prunes low-relevance semantic facts\n- **ZettelPruneEvolver**: Merges duplicate or low-quality notes\n\nEvolvers run automatically as part of the memory lifecycle. See the [examples](examples/) directory for evolution demonstrations.\n\n## Plugin System\n\nSmartMemory features a **unified, extensible plugin architecture** that allows you to customize and extend functionality. All plugins follow a consistent class-based pattern.\n\n### Built-in Plugins\n\nSmartMemory includes **18 built-in plugins** across 4 types:\n\n- **4 Extractors**: Extract entities and relationships\n - `SpacyExtractor`, `LLMExtractor`, `RebelExtractor`, `RelikExtractor`\n- **6 Enrichers**: Add context and metadata to memories\n - `BasicEnricher`, `SentimentEnricher`, `TemporalEnricher`, `TopicEnricher`, `SkillsToolsEnricher`, `WikipediaEnricher`\n- **1 Grounder**: Connect to external knowledge\n - `WikipediaGrounder`\n- **7 Evolvers**: Transform memories based on rules\n - `WorkingToEpisodicEvolver`, `EpisodicToSemanticEvolver`, `SemanticDecayEvolver`, etc.\n\n### Creating Custom Plugins\n\nCreate your own plugins by extending the base classes:\n\n```python\nfrom smartmemory.plugins.base import EnricherPlugin, PluginMetadata\n\nclass MyCustomEnricher(EnricherPlugin):\n @classmethod\n def metadata(cls):\n return PluginMetadata(\n name=\"my_enricher\",\n version=\"1.0.0\",\n author=\"Your Name\",\n description=\"My custom enricher\",\n plugin_type=\"enricher\",\n dependencies=[\"some-lib>=1.0.0\"],\n security_profile=\"standard\",\n requires_network=False,\n requires_llm=False\n )\n \n def enrich(self, item, node_ids=None):\n # Your enrichment logic\n item.metadata[\"custom_field\"] = \"value\"\n return item.metadata\n```\n\nSee the [examples](examples/) directory for complete plugin examples.\n\n### Publishing Plugins\n\nPublish your plugin as a Python package with entry points:\n\n```toml\n# pyproject.toml\n[project.entry-points.\"smartmemory.plugins.enrichers\"]\nmy_enricher = \"my_package:MyCustomEnricher\"\n```\n\nInstall and use:\n```bash\npip install my-smartmemory-plugin\n# Automatically discovered and loaded!\n```\n\n### Plugin Types\n\n- **ExtractorPlugin**: Extract entities and relationships from text\n- **EnricherPlugin**: Add metadata and context to memories\n- **GrounderPlugin**: Link memories to external knowledge sources\n- **EvolverPlugin**: Transform memories based on conditions\n\nAll plugins are automatically discovered and registered at startup.\n\n### Plugin Security\n\nSmartMemory includes a comprehensive security system for plugins:\n\n- **4 Security Profiles**: `trusted`, `standard` (default), `restricted`, `untrusted`\n- **Permission System**: Control memory, network, file, and LLM access\n- **Resource Limits**: Automatic timeout (30s), memory limits, network request limits\n- **Sandboxing**: Isolated execution with security enforcement\n- **Static Validation**: Detects security issues before execution\n\n```python\n# Plugins are secure by default\nPluginMetadata(\n security_profile=\"standard\", # Balanced security\n requires_network=True, # Explicitly declare requirements\n requires_llm=False\n)\n```\n\nSee `docs/PLUGIN_SECURITY.md` for complete security documentation.\n\n### Examples\n\nSee the `examples/` directory for complete plugin examples:\n- `custom_enricher_example.py` - Sentiment analysis and keyword extraction\n- `custom_evolver_example.py` - Memory promotion and archival\n- `custom_extractor_example.py` - Regex and domain-specific NER\n- `custom_grounder_example.py` - DBpedia and custom API grounding\n\n## Testing\n\nRun the test suite:\n\n```bash\n# Run all tests\nPYTHONPATH=. pytest -v tests/\n\n# Run specific test categories\nPYTHONPATH=. pytest tests/unit/\nPYTHONPATH=. pytest tests/integration/\nPYTHONPATH=. pytest tests/e2e/\n\n# Run examples\nPYTHONPATH=. python examples/memory_system_usage_example.py\nPYTHONPATH=. python examples/conversational_assistant_example.py\n```\n\n## API Reference\n\n### SmartMemory Class\n\nMain interface for memory operations:\n\n```python\nclass SmartMemory:\n def add(self, item: MemoryItem) -> Optional[MemoryItem]\n def get(self, item_id: str) -> Optional[MemoryItem]\n def search(self, query: str, top_k: int = 10) -> List[MemoryItem]\n def delete(self, item_id: str) -> bool\n def clear(self) -> None\n def summary(self) -> Dict[str, Any]\n def ingest(self, content: str, **kwargs) -> MemoryItem\n```\n\n### MemoryItem Class\n\nCore data structure for memory storage:\n\n```python\n@dataclass\nclass MemoryItem:\n content: str\n memory_type: str = 'semantic'\n item_id: str = field(default_factory=lambda: str(uuid.uuid4()))\n user_id: Optional[str] = None\n group_id: Optional[str] = None\n valid_start_time: Optional[datetime] = None\n valid_end_time: Optional[datetime] = None\n transaction_time: datetime = field(default_factory=datetime.now)\n embedding: Optional[List[float]] = None\n entities: Optional[list] = None\n relations: Optional[list] = None\n metadata: dict = field(default_factory=dict)\n```\n\n## Dependencies\n\n### Core Dependencies\n\nSmartMemory requires the following key dependencies:\n\n- `falkordb`: Graph database and vector storage backend\n- `spacy`: Natural language processing and entity extraction\n- `litellm`: LLM integration layer\n- `openai`: OpenAI API client (for embeddings)\n- `redis`: Caching layer\n- `scikit-learn`: Machine learning utilities\n- `pydantic`: Data validation\n- `python-dateutil`: Date/time handling\n- `vaderSentiment`: Sentiment analysis\n- `jinja2`: Template rendering\n\n**Note:** SmartMemory uses FalkorDB for both graph and vector storage. While the codebase contains legacy ChromaDB integration code, FalkorDB is the primary and recommended backend.\n\n### Optional Dependencies\n\nInstall additional features as needed:\n\n```bash\n# Specific extractors\npip install smartmemory[rebel] # REBEL relation extraction\npip install smartmemory[relik] # ReliK relation extraction\n\n# Integrations\npip install smartmemory[slack] # Slack integration\npip install smartmemory[aws] # AWS integration\npip install smartmemory[wikipedia] # Wikipedia enrichment\n\n# Tools\npip install smartmemory[cli] # Command-line interface\n\n# Everything\npip install smartmemory[all] # All optional features\n```\n\n## Contributing\n\nContributions are welcome! Please follow these guidelines:\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure all tests pass\n5. Submit a pull request\n\nFor major changes, please open an issue first to discuss the proposed changes.\n\n## \ud83d\udcc4 License\n\nSmartMemory is dual-licensed to provide flexibility for both open-source and commercial use. See [LICENSE](LICENSE) for details.\n\n## Security\n\nSmartMemory takes plugin security seriously. All plugins run in a sandboxed environment with:\n\n- \u2705 **Permission checks** - Plugins must declare what they access\n- \u2705 **Resource limits** - Automatic timeouts and memory limits\n- \u2705 **Execution isolation** - Sandboxed plugin execution\n- \u2705 **Static analysis** - Security validation before execution\n\nExternal plugins use the `standard` security profile by default. See `docs/PLUGIN_SECURITY.md` for details.\n\n## \ud83d\udd17 Links\n\n- **\ud83d\udce6 PyPI Package**: https://pypi.org/project/smartmemory/\n- **\ud83d\udcda Documentation**: https://docs.smartmemory.ai\n- **\ud83d\udc19 GitHub Repository**: https://github.com/smart-memory/smart-memory\n- **\ud83d\udc1b Issue Tracker**: https://github.com/smart-memory/smart-memory/issues\n- **\ud83d\udd12 Security Policy**: See `docs/PLUGIN_SECURITY.md`\n- **\ud83d\ude80 Production Service**: https://github.com/smart-memory/smart-memory-service\n\n---\n\n**Get started with SmartMemory today!**\n\n```bash\npip install smartmemory\n```\n\nExplore the [examples](examples/) directory for complete demonstrations and use cases.\n\n---\n\n## \ud83d\udea7 In Progress\n\nThe following features are currently under active development:\n\n### Ontology System\n- **Current**: Basic concept and relation extraction\n- **In Progress**: \n - Ontology governance and validation\n - External ontology integration (DBpedia, Schema.org)\n - Semantic clustering and concept hierarchies\n - Ontology-driven query expansion\n- **Planned**: Full ontology management with Maya integration\n\n### Temporal Queries\n- **Current**: Basic bi-temporal support (valid_time, transaction_time)\n- **In Progress**:\n - Time-travel queries\n - Version history tracking\n - Audit trail generation\n- **Planned**: Advanced temporal analytics\n\n### Multi-Tenancy (Service Layer)\n- **Current**: Single-user mode\n- **In Progress**: Full multi-tenancy support in smart-memory-service\n- **Planned**: Team collaboration features\n\nThese features are functional but not yet production-ready. Check the [GitHub repository](https://github.com/smart-memory/smart-memory) for the latest updates.\n",
"bugtrack_url": null,
"license": "AGPL-3.0",
"summary": "Multi-layered AI memory system with graph databases, vector stores, and intelligent processing pipelines",
"version": "0.1.11",
"project_urls": {
"Bug Tracker": "https://github.com/smart-memory/smart-memory/issues",
"Documentation": "https://docs.smartmemory.ai",
"Homepage": "https://github.com/smart-memory/smart-memory",
"Repository": "https://github.com/smart-memory/smart-memory"
},
"split_keywords": [
"ai",
" memory",
" graph-database",
" vector-database",
" llm",
" knowledge-graph",
" semantic-memory",
" episodic-memory",
" rag",
" embeddings"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "af6cc2ff3be5b986e3e802cf5524aa28f723674b2f149824e2af49a57b9cf57a",
"md5": "2ca6cd443a8cf6a3b86d6ff74684339a",
"sha256": "3c8eea0bfa9d806df094d3d4ef118b33cc967b3ad8325024b937b2e9c1b98465"
},
"downloads": -1,
"filename": "smartmemory-0.1.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2ca6cd443a8cf6a3b86d6ff74684339a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 543207,
"upload_time": "2025-10-20T18:39:50",
"upload_time_iso_8601": "2025-10-20T18:39:50.812979Z",
"url": "https://files.pythonhosted.org/packages/af/6c/c2ff3be5b986e3e802cf5524aa28f723674b2f149824e2af49a57b9cf57a/smartmemory-0.1.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2fe82775d8ae1a33a5a61113027bec413a077d17a353f90e0ac14acc7bf196ed",
"md5": "2578a4555bce5a8bd90641fb8e850746",
"sha256": "c0eb04ffeeb37d9f89b2d1a4e2049775accbc50b3054c84324d06f553ccd71c5"
},
"downloads": -1,
"filename": "smartmemory-0.1.11.tar.gz",
"has_sig": false,
"md5_digest": "2578a4555bce5a8bd90641fb8e850746",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 424431,
"upload_time": "2025-10-20T18:39:52",
"upload_time_iso_8601": "2025-10-20T18:39:52.464049Z",
"url": "https://files.pythonhosted.org/packages/2f/e8/2775d8ae1a33a5a61113027bec413a077d17a353f90e0ac14acc7bf196ed/smartmemory-0.1.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-20 18:39:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "smart-memory",
"github_project": "smart-memory",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "smolagents",
"specs": []
},
{
"name": "wikipedia-api",
"specs": []
},
{
"name": "python-dateutil",
"specs": []
},
{
"name": "slack-sdk",
"specs": []
},
{
"name": "spacy",
"specs": []
},
{
"name": "vaderSentiment",
"specs": []
},
{
"name": "falkordb",
"specs": []
},
{
"name": "jinja2",
"specs": []
},
{
"name": "litellm",
"specs": []
},
{
"name": "openai",
"specs": []
},
{
"name": "scikit-learn",
"specs": []
},
{
"name": "slack_sdk",
"specs": []
},
{
"name": "boto3",
"specs": []
},
{
"name": "dspy",
"specs": []
}
],
"lcname": "smartmemory"
}
JSON
