Metadata-Version: 2.4
Name: greeum
Version: 3.1.1rc2.dev4
Summary: Context-Dependent Neural Memory System for LLMs with GraphIndex beam search, STM/LTM consolidation, and semantic tagging
Author-email: DryRainEnt <kachirjsdn@gmail.com>
License-Expression: MIT
Keywords: memory,LLM,RAG
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.4.0
Requires-Dist: click>=8.1.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: anyio>=4.5
Requires-Dist: requests>=2.25.0
Requires-Dist: flask>=2.0.0
Requires-Dist: flask-restx>=0.5.1
Requires-Dist: flask-cors>=3.0.10
Requires-Dist: python-dotenv>=0.19.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: sentence-transformers>=2.2.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: responses>=0.23.0; extra == "test"
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: full
Requires-Dist: sentence-transformers>=2.2.0; extra == "full"
Requires-Dist: openai>=0.27.0; extra == "full"
Requires-Dist: faiss-cpu>=1.7.4; extra == "full"
Requires-Dist: keybert>=0.7.0; extra == "full"
Requires-Dist: scikit-learn>=1.3.0; extra == "full"
Requires-Dist: transformers>=4.40.0; extra == "full"
Requires-Dist: spacy>=3.5.0; extra == "full"
Dynamic: license-file

# Greeum

[![PyPI version](https://badge.fury.io/py/greeum.svg)](https://badge.fury.io/py/greeum)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

AI conversations that remember everything.
No more repeating context every time.

## ⚡ Quick Start

```bash
# Install
pip install greeum

# Add your first memory
greeum memory add "Started working on the new dashboard project"

# Set memory anchors for quick access
greeum anchors set A 123  # Pin important memory to slot A

# Search with anchor-based localization
greeum memory search "dashboard project" --slot A --radius 2
```

That's it. Your AI now remembers.

## ✨ What It Does

🧠 **Remembers context** - AI recalls previous conversations and decisions
⚡ **280x faster search** - Checkpoint-based memory retrieval
🔄 **Works with any AI** - GPT, Claude, or your custom model
🛡️ **Your data stays yours** - Local storage, no cloud required

## 🔧 Installation

### Basic Setup
```bash
pip install greeum
```

### With All Features
```bash
pip install greeum[all]  # includes vector search, embeddings
```

### For Claude Code Users
```bash
# Install and start MCP server
pip install greeum
greeum mcp serve
```

## 📝 Usage

### Adding Memories
```bash
# Add important context
greeum memory add "Client prefers minimal UI design"

# Add with expiration
greeum stm add "Working on login page today" --ttl 24h
```

### Memory Anchors (v2.2.5+)
```bash
# View current anchor status
greeum anchors status

# Set anchors for quick access
greeum anchors set A 123     # Pin memory #123 to slot A
greeum anchors set B 456     # Pin memory #456 to slot B

# Search near anchored memories
greeum memory search "UI design" --slot A --radius 3

# Pin/unpin anchors
greeum anchors pin A         # Prevent auto-movement
greeum anchors unpin A       # Allow auto-movement

# Clear all anchors
greeum anchors clear
```

### Searching
```bash
# Find relevant memories
greeum memory search "UI design preferences" --count 5

# Anchor-based localized search (faster)
greeum memory search "login" --slot B --radius 2 --fallback

# Global search (traditional)
greeum memory search "login" --count 10
```

### Python API
```python
from greeum import BlockManager, DatabaseManager

# Initialize
db_manager = DatabaseManager()
memory = BlockManager(db_manager)

# Add block to long-term memory
block = memory.add_block(
    context="User wants dark mode toggle",
    keywords=["dark", "mode", "toggle"],
    tags=["ui", "preference"],
    embedding=[],  # Auto-generated if empty
    importance=0.7
)

# Search memories
results = memory.search_memories("dark mode", limit=3)
```

## 🤖 Claude Integration

### Setup MCP Server
Add to your Claude Desktop config:

```json
{
  "mcpServers": {
    "greeum": {
      "command": "greeum",
      "args": ["mcp", "serve"],
      "env": {
        "GREEUM_DATA_DIR": "/path/to/your/data"
      }
    }
  }
}
```

### Available Tools
- `add_memory` - Store important context
- `search_memory` - Find relevant memories
- `get_memory_stats` - View memory statistics

## 📚 Documentation

- [Getting Started](docs/get-started.md) - Installation and first steps
- [API Reference](docs/api-reference.md) - Complete API documentation
- [MCP Integration](docs/mcp-integration.md) - Claude Code setup

## 🏗️ Architecture

```
Your Input → Working Memory → Cache → Checkpoints → Long-term Storage
             0.04ms          0.08ms   0.7ms        Permanent
```

Four-layer memory system optimized for speed and relevance.

## 📋 Version Updates

### v2.1.1 (2025-08)
- Enhanced search with temporal boost for recent information prioritization
- Optimized codebase with 955 lines of code reduction and improved test architecture
- Resolved import dependencies and improved memory management
- Added intelligent date keyword detection for search result ranking
- Improved test stability with BaseGreeumTestCase standardization
- Performance optimizations with minimal overhead (+1.0%)

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch
3. Submit a pull request

See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## 📄 License

MIT License - see [LICENSE](LICENSE) file.

---

**Greeum** - Memory for AI that actually works.
Made with ❤️ by the open source community.
