Metadata-Version: 2.4
Name: memg-core
Version: 0.1.dev77
Summary: Lightweight memory system for AI agents with vector search and graph storage
Author-email: Genovo AI <dev@genovo.ai>
License-Expression: MIT
Project-URL: Homepage, https://github.com/genovo-ai/memg-core
Project-URL: Repository, https://github.com/genovo-ai/memg-core
Project-URL: Issues, https://github.com/genovo-ai/memg-core/issues
Keywords: ai,memory,vector-search,graph-database,mcp,agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Database
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: qdrant-client>=1.14.0
Requires-Dist: kuzu==0.11.1
Requires-Dist: pydantic<3.0.0,>=2.11.7
Requires-Dist: pydantic-core<3.0.0,>=2.33.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: google-genai>=1.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: typing-extensions>=4.12.0
Requires-Dist: httpx>=0.28.0
Provides-Extra: dev
Requires-Dist: ruff>=0.12.0; extra == "dev"
Requires-Dist: pylint>=3.3.7; extra == "dev"
Requires-Dist: pre-commit>=4.2.0; extra == "dev"
Requires-Dist: pytest>=8.4.1; extra == "dev"
Requires-Dist: pytest-asyncio>=0.25.0; extra == "dev"
Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
Requires-Dist: bandit>=1.8.6; extra == "dev"
Requires-Dist: mypy>=1.17.0; extra == "dev"
Requires-Dist: black>=25.1.0; extra == "dev"
Requires-Dist: isort>=6.0.1; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=8.4.1; extra == "test"
Requires-Dist: pytest-asyncio>=0.25.0; extra == "test"
Dynamic: license-file

# MEMG Core

**Lightweight memory system for AI agents with dual storage (Qdrant + Kuzu)**

## Features

- **Vector Search**: Fast semantic search with Qdrant
- **Graph Storage**: Optional relationship analysis with Kuzu
- **AI Integration**: Automated entity extraction with Google Gemini
- **MCP Compatible**: Ready-to-use MCP server for AI agents
- **Lightweight**: Minimal dependencies, optimized for performance

## Quick Start

### Option 1: Docker (Recommended)
```bash
# 1. Create configuration
cp env.example .env
# Edit .env and set your GOOGLE_API_KEY

# 2. Run MEMG MCP Server (359MB)
docker run -d \
  -p 8787:8787 \
  --env-file .env \
  ghcr.io/genovo-ai/memg-core-mcp:latest

# 3. Test it's working
curl http://localhost:8787/health
```

### Option 2: Python Package (Core Library)
```bash
pip install memg-core

# Set up environment (for examples/tests)
cp env.example .env
# Edit .env and set your GOOGLE_API_KEY

# Use the core library in your app; the MCP server is provided via Docker image
# Example usage shown below in the Usage section.
```

### Development setup
```bash
# 1) Create virtualenv and install slim runtime deps for library usage
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 2) For running tests and linters locally, install dev deps
pip install -r requirements-dev.txt

# 3) Run tests
export MEMG_TEMPLATE="software_development"
export QDRANT_STORAGE_PATH="$HOME/.local/share/qdrant"
export KUZU_DB_PATH="$HOME/.local/share/kuzu/memg.db"
mkdir -p "$QDRANT_STORAGE_PATH" "$HOME/.local/share/kuzu"
PYTHONPATH=$(pwd)/src pytest -q
```

## Usage

```python
from memg_core import add_memory, search_memories
from memg_core.models.core import Memory, MemoryType

# Add a note
note = Memory(user_id="u1", content="Python is great for AI", memory_type=MemoryType.NOTE)
add_memory(note)

# Search
import asyncio
asyncio.run(search_memories("python ai", user_id="u1"))
```

### YAML registries (optional)

Core ships with three tiny registries under `integration/config/`:

- `core.minimal.yaml`: basic types `note`, `document`, `task` with anchors and generic relations
- `core.software_dev.yaml`: adds `bug` + `solution` and `bug_solution` relation
- `core.knowledge.yaml`: `concept` + `document` with `mentions`/`derived_from`

Enable:

```bash
export MEMG_ENABLE_YAML_SCHEMA=true
export MEMG_YAML_SCHEMA=$(pwd)/integration/config/core.minimal.yaml
```

## Evaluation

Use the built-in scripts to generate a synthetic dataset that covers all entity and memory types, and then run repeatable evaluations each iteration.

### 1) Generate dataset
```bash
python scripts/generate_synthetic_dataset.py \
  --output ./data/memg_synth.jsonl \
  --num 200 \
  --user eval_user
```

This creates JSONL rows containing a `memory` plus associated `entities` and `relationships`, exercising:
- All `EntityType` values (TECHNOLOGY, DATABASE, COMPONENT, ERROR, SOLUTION, FILE_TYPE, etc.)
- Multiple `MemoryType`s: document, note, conversation, task
- Basic `MENTIONS` relationships

### 2) Offline validation (no external services)
Validates schema and database compatibility quickly without embeddings or storage.
```bash
python scripts/evaluate_memg.py --data ./data/memg_synth.jsonl --mode offline
```
Output summary includes rows, counts, and error/warning totals to track across iterations.

### 3) Live processing (embeddings + storage)
Requires environment configured (e.g., `GOOGLE_API_KEY`) and storage reachable. It runs the Unified pipeline and validates the resulting memories.
```bash
python scripts/evaluate_memg.py --data ./data/memg_synth.jsonl --mode live
```

Tip: Commit the dataset and compare results over time in CI to catch regressions.

## Configuration

Configure via `.env` file (copy from `env.example`):

```bash
# Required
GOOGLE_API_KEY=your_google_api_key_here

# Core settings
GEMINI_MODEL=gemini-2.0-flash
MEMORY_SYSTEM_MCP_PORT=8787
MEMG_TEMPLATE=software_development

# Storage
BASE_MEMORY_PATH=$HOME/.local/share/memory_system
QDRANT_COLLECTION=memories
EMBEDDING_DIMENSION_LEN=768
```

## Requirements

- Python 3.11+
- Google API key for Gemini

## Links

- [Repository](https://github.com/genovo-ai/memg-core)
- [Issues](https://github.com/genovo-ai/memg-core/issues)
- [Documentation](https://github.com/genovo-ai/memg-core#readme)

## License

MIT License - see LICENSE file for details.
