Metadata-Version: 2.4
Name: agentic-graph-mem
Version: 1.0.3
Summary: Production-Grade Agent Memory Framework for Agentic AI
Project-URL: Homepage, https://github.com/ameerai/graphmem
Project-URL: Documentation, https://graphmem.readthedocs.io
Project-URL: Repository, https://github.com/ameerai/graphmem
Project-URL: Issues, https://github.com/ameerai/graphmem/issues
Author-email: Ameer AI <ameer@ameerai.com>
License: MIT
License-File: LICENSE
Keywords: agent,agentic-ai,ai,embedding,graphrag,knowledge-graph,llm,memory,neo4j,rag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: networkx>=3.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: all
Requires-Dist: anthropic>=0.25.0; extra == 'all'
Requires-Dist: beautifulsoup4>=4.12.0; extra == 'all'
Requires-Dist: neo4j>=5.0.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Requires-Dist: pillow>=9.0.0; extra == 'all'
Requires-Dist: pymupdf>=1.23.0; extra == 'all'
Requires-Dist: pytesseract>=0.3.10; extra == 'all'
Requires-Dist: redis>=4.0.0; extra == 'all'
Requires-Dist: requests>=2.31.0; extra == 'all'
Requires-Dist: sentence-transformers>=2.2.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.25.0; extra == 'anthropic'
Provides-Extra: audio
Requires-Dist: openai-whisper>=20231117; extra == 'audio'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: beautifulsoup4>=4.12.0; extra == 'docs'
Requires-Dist: openai-whisper>=20231117; extra == 'docs'
Requires-Dist: pillow>=9.0.0; extra == 'docs'
Requires-Dist: pymupdf>=1.23.0; extra == 'docs'
Requires-Dist: pytesseract>=0.3.10; extra == 'docs'
Requires-Dist: requests>=2.31.0; extra == 'docs'
Provides-Extra: llm
Requires-Dist: anthropic>=0.25.0; extra == 'llm'
Requires-Dist: openai>=1.0.0; extra == 'llm'
Provides-Extra: local
Requires-Dist: sentence-transformers>=2.2.0; extra == 'local'
Provides-Extra: neo4j
Requires-Dist: neo4j>=5.0.0; extra == 'neo4j'
Provides-Extra: ocr
Requires-Dist: pillow>=9.0.0; extra == 'ocr'
Requires-Dist: pytesseract>=0.3.10; extra == 'ocr'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Provides-Extra: pdf
Requires-Dist: pymupdf>=1.23.0; extra == 'pdf'
Provides-Extra: redis
Requires-Dist: redis>=4.0.0; extra == 'redis'
Provides-Extra: storage
Requires-Dist: neo4j>=5.0.0; extra == 'storage'
Requires-Dist: redis>=4.0.0; extra == 'storage'
Provides-Extra: web
Requires-Dist: beautifulsoup4>=4.12.0; extra == 'web'
Requires-Dist: requests>=2.31.0; extra == 'web'
Description-Content-Type: text/markdown

# 🧠 GraphMem

**Production-Grade Agent Memory Framework for Agentic AI**

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

GraphMem is a state-of-the-art, self-evolving graph-based memory system designed for production-scale agentic AI applications. It provides human-like memory capabilities with automatic consolidation, decay, and rehydration—all built on enterprise-grade storage backends.

## ✨ Key Features

### 🔄 Self-Evolving Memory
- **Memory Consolidation**: Automatically merges related memories into coherent knowledge
- **Importance Decay**: Less relevant memories naturally fade over time
- **Rehydration**: Revive and strengthen memories when accessed
- **Continuous Learning**: Memory improves through usage patterns

### 🕸️ Graph-Based Knowledge
- **Entity Resolution**: Intelligent deduplication and canonicalization
- **Community Detection**: Automatic topic clustering
- **Rich Relationships**: Capture complex entity connections
- **Semantic Search**: Find relevant context by meaning

### 📚 Multi-Modal Context Engineering
- **Text Documents**: Intelligent chunking with semantic boundaries
- **PDFs**: Extract text, images, and tables
- **Images**: OCR and vision model analysis
- **Audio**: Transcription to text
- **Web Pages**: Smart content extraction
- **Code Files**: Language-aware chunking
- **Structured Data**: JSON, CSV processing

### 🚀 Production Ready
- **Neo4j Backend**: Enterprise graph database
- **Redis Caching**: Sub-millisecond retrieval
- **Parallel Processing**: Concurrent knowledge extraction
- **Retry Logic**: Resilient to transient failures
- **Scalable**: Handles millions of memories

## 🏁 Quick Start

### Installation

```bash
pip install agentic-graph-mem
```

Or with all dependencies:

```bash
pip install agentic-graph-mem[all]
```

### Basic Usage

```python
from graphmem import GraphMem

# Initialize with sensible defaults
memory = GraphMem()

# Ingest information
memory.ingest("""
TechCorp announced today that John Smith has been appointed as their new CEO.
Smith brings 20 years of experience from leading AI companies including DeepMind
and OpenAI. The company's stock rose 15% on the news.
""")

# Query the memory
response = memory.query("Who is the new CEO of TechCorp?")
print(response.answer)
# Output: "John Smith has been appointed as the new CEO of TechCorp."

# Memory evolves automatically
memory.evolve()
```

### Configuration

```python
from graphmem import GraphMem, MemoryConfig

config = MemoryConfig(
    # LLM settings
    llm_provider="azure_openai",
    llm_api_key="your-api-key",
    llm_endpoint="https://your-endpoint.openai.azure.com",
    llm_deployment="gpt-4o",
    
    # Embedding settings
    embedding_provider="azure_openai",
    embedding_deployment="text-embedding-3-small",
    
    # Storage settings
    neo4j_uri="bolt://localhost:7687",
    neo4j_user="neo4j",
    neo4j_password="password",
    
    # Cache settings
    redis_url="redis://localhost:6379",
    
    # Evolution settings
    auto_evolve=True,
    evolution_interval=3600,  # seconds
    consolidation_threshold=0.85,
    decay_rate=0.01,
)

memory = GraphMem(config)
```

## 🏗️ Architecture

```
GraphMem
├── Core
│   ├── GraphMem          # Main interface
│   ├── Memory            # Memory unit (nodes, edges, clusters)
│   ├── MemoryNode        # Entity representation
│   ├── MemoryEdge        # Relationship representation
│   └── MemoryCluster     # Community/topic grouping
│
├── Graph
│   ├── KnowledgeGraph    # Knowledge extraction & storage
│   ├── EntityResolver    # Entity deduplication
│   └── CommunityDetector # Topic clustering
│
├── Evolution
│   ├── MemoryEvolution   # Evolution orchestrator
│   ├── MemoryDecay       # Importance decay
│   ├── Consolidation     # Memory merging
│   └── Rehydration       # Memory restoration
│
├── Retrieval
│   ├── QueryEngine       # Query processing
│   ├── MemoryRetriever   # Context retrieval
│   └── SemanticSearch    # Embedding search
│
├── Context
│   ├── ContextEngine     # Context window construction
│   ├── DocumentChunker   # Semantic chunking
│   └── MultiModalProcessor # Multi-modal handling
│
├── LLM
│   ├── LLMProvider       # LLM abstraction
│   └── EmbeddingProvider # Embedding abstraction
│
└── Stores
    ├── Neo4jStore        # Graph persistence
    └── RedisCache        # Caching layer
```

## 📖 Advanced Usage

### Custom Knowledge Extraction

```python
from graphmem import GraphMem, KnowledgeGraph

# Create with custom extraction prompt
memory = GraphMem(
    extraction_prompt="""
    Extract entities and relationships from the text.
    Focus on: People, Organizations, Products, Events
    
    Text: {text}
    """
)
```

### Multi-Modal Ingestion

```python
from graphmem import GraphMem

memory = GraphMem()

# Ingest PDF
memory.ingest_file("report.pdf", modality="pdf")

# Ingest image
memory.ingest_file("diagram.png", modality="image")

# Ingest audio (transcribes automatically)
memory.ingest_file("meeting.mp3", modality="audio")

# Ingest web page
memory.ingest_url("https://example.com/article")

# Ingest code
memory.ingest_file("main.py", modality="code")
```

### Manual Evolution Control

```python
from graphmem import GraphMem, MemoryConfig

config = MemoryConfig(auto_evolve=False)
memory = GraphMem(config)

# Add content
memory.ingest("...")

# Manually trigger evolution
memory.consolidate()  # Merge similar memories
memory.decay()        # Apply importance decay
memory.prune()        # Remove low-importance memories
```

### Query with Filters

```python
response = memory.query(
    "What happened at TechCorp?",
    filters={
        "entity_type": "Organization",
        "min_importance": 5,
    },
    top_k=20,
    include_context=True,
)

print(response.answer)
print(response.confidence)
print(response.context)
```

### Direct Graph Access

```python
from graphmem import GraphMem

memory = GraphMem()

# Get entities
entities = memory.get_entities(entity_type="Person")

# Get relationships
relationships = memory.get_relationships(
    source="John Smith",
    relation_type="CEO_OF"
)

# Get communities
communities = memory.get_communities()
```

## 🔧 Configuration Options

| Option | Description | Default |
|--------|-------------|---------|
| `llm_provider` | LLM provider (azure_openai, openai, anthropic, ollama) | `azure_openai` |
| `embedding_provider` | Embedding provider | `azure_openai` |
| `neo4j_uri` | Neo4j connection URI | `bolt://localhost:7687` |
| `redis_url` | Redis connection URL | `redis://localhost:6379` |
| `auto_evolve` | Enable automatic memory evolution | `True` |
| `evolution_interval` | Seconds between evolution cycles | `3600` |
| `consolidation_threshold` | Similarity threshold for merging | `0.85` |
| `decay_rate` | Daily decay rate for importance | `0.01` |
| `chunk_size` | Document chunk size in characters | `1000` |
| `chunk_overlap` | Chunk overlap in characters | `200` |
| `top_k` | Default number of retrieval results | `10` |
| `min_similarity` | Minimum similarity for retrieval | `0.5` |

## 🧪 Testing

```bash
# Run tests
pytest tests/

# Run with coverage
pytest tests/ --cov=graphmem

# Run specific test
pytest tests/test_memory.py::test_ingestion
```

## 📦 Dependencies

### Required
- Python 3.9+
- numpy
- pydantic

### Optional (by feature)
- **LLM**: openai, anthropic
- **Storage**: neo4j, redis
- **PDF**: PyMuPDF or PyPDF2
- **OCR**: pytesseract, Pillow
- **Audio**: openai-whisper
- **Web**: beautifulsoup4, requests
- **Local Embeddings**: sentence-transformers

## 🤝 Contributing

Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

## 🙏 Acknowledgments

Built with inspiration from:
- GraphRAG by Microsoft
- LlamaIndex
- Human cognitive science research on memory consolidation

---

**Made with ❤️ by Ameer AI**

