Metadata-Version: 2.4
Name: memgraph-agent
Version: 0.2.1
Summary: Universal plug-and-play memory engine for AI agents. Built on Graphiti's temporal knowledge graph with token-budget optimization.
Project-URL: Homepage, https://github.com/SP3DK1D/Memomatic
Project-URL: Repository, https://github.com/SP3DK1D/Memomatic
Project-URL: Issues, https://github.com/SP3DK1D/Memomatic/issues
Project-URL: Documentation, https://github.com/SP3DK1D/Memomatic#readme
Project-URL: Changelog, https://github.com/SP3DK1D/Memomatic/releases
Author-email: "Luke (TechItLuke)" <techitluke@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,graphiti,knowledge-graph,llm,mcp,memory,rag,token-budget
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: faiss-cpu>=1.8.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: graphiti-core[falkordb]>=0.3.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: pydantic-settings>=2.4.0
Requires-Dist: pydantic>=2.8.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: structlog>=24.4.0
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: all
Requires-Dist: anthropic>=0.34.0; extra == 'all'
Requires-Dist: langchain>=0.2.0; extra == 'all'
Requires-Dist: openai>=1.40.0; extra == 'all'
Requires-Dist: sentence-transformers>=3.0.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.34.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain>=0.2.0; extra == 'langchain'
Provides-Extra: local
Requires-Dist: sentence-transformers>=3.0.0; extra == 'local'
Provides-Extra: openai
Requires-Dist: openai>=1.40.0; extra == 'openai'
Provides-Extra: voyage
Requires-Dist: voyageai>=0.2.0; extra == 'voyage'
Description-Content-Type: text/markdown

# MemGraph — Universal AI Agent Memory Engine

[![PyPI version](https://img.shields.io/pypi/v/memgraph-agent?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/memgraph-agent/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue?logo=python&logoColor=white)](https://python.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/SP3DK1D/Memomatic/ci.yml?branch=main&label=CI&logo=github)](https://github.com/SP3DK1D/Memomatic/actions)
[![Coverage](https://img.shields.io/badge/coverage-80%25%2B-brightgreen)](https://github.com/SP3DK1D/Memomatic/actions)
[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-blueviolet)](https://modelcontextprotocol.io)
[![Docker](https://img.shields.io/badge/docker-compose-2496ED?logo=docker&logoColor=white)](docker-compose.yml)

> **Give any AI agent perfect memory in 3 lines of code.**

MemGraph wraps [Graphiti](https://github.com/getzep/graphiti)'s temporal knowledge graph with a **token-budget allocator** that packs the maximum signal into the minimum tokens. Most agent turns need zero long-term memory — those turns pay zero memory tokens.

---

## The Problem

Every "agent memory" system does one of two dumb things:

| Approach | Problem |
|---|---|
| Dump the whole history | Wastes thousands of tokens every turn. Expensive and slow. |
| Summarise into one paragraph | Lossy. Misses important details. Can't answer precise questions. |

## The MemGraph Solution

```
Knowledge graph + hybrid retrieval + token-budget allocator
```

1. **Knowledge graph storage** — facts, entities, and temporal relationships via Graphiti + FalkorDB.
2. **Hybrid retrieval** — FAISS vector search + graph neighbour expansion + BM25, re-ranked by relevance × recency × centrality.
3. **Token-budget allocator** — given a hard ceiling (e.g. 1000 tokens), pack the most information-dense fragments that fit. When nothing is relevant, return empty — saving 100% of memory tokens.

---

## Benchmark Results

> Measured on a synthetic 40-turn conversation with 10 test queries.
> Hardware: Ryzen 5800H, 32GB DDR4, nomic-embed-text (local).

| Approach | Avg Tokens / Query | P95 Latency | Token Reduction |
|---|---|---|---|
| Raw context (full history) | ~3,200 | — | baseline |
| Sliding window (10 turns) | ~820 | — | −74% |
| **MemGraph (budget=1000)** | **~310** | **< 30ms** | **−90%** |

Run the benchmarks yourself:

```bash
uv run python benchmarks/token_comparison.py --turns 40 --budget 1000
uv run python benchmarks/retrieval_speed.py  --facts 200 --queries 50
uv run python benchmarks/quality_eval.py     --budget 800
```

---

## Quickstart

### Install

```bash
pip install memgraph-agent
```

### Check prerequisites (Docker, FalkorDB, Ollama)

```bash
memgraph-setup        # check only
memgraph-setup --fix  # auto-start missing services
```

### One-command infra

```bash
docker compose up -d  # starts FalkorDB on :6379 and :3000 (browser UI)
```

### Use it

```python
from memgraph import MemGraph

async with await MemGraph.create() as mg:
    # Store anything — plain text, messages, JSON
    await mg.store("Luke prefers TypeScript and runs Ollama locally.")
    await mg.store([
        {"role": "user",      "content": "What's the ATLAS stack?"},
        {"role": "assistant", "content": "Express.js + Qwen3 via Ollama."},
    ])

    # Retrieve — only pays token cost when relevant context exists
    ctx = await mg.query("What stack does Luke use?", token_budget=500)
    print(ctx.text)          # formatted, token-capped, ready to inject
    print(ctx.tokens_used)   # exact token count (0 if nothing relevant)
    print(ctx.is_empty)      # True when nothing relevant found
```

That's it. No vector DB setup, no embedding server to manage (uses Ollama locally by default).

---

## Install Options

```bash
# Minimal (core + REST server + MCP)
pip install memgraph-agent

# With OpenAI client (for OpenAI Agents SDK adapter)
pip install memgraph-agent[openai]

# With Anthropic client
pip install memgraph-agent[anthropic]

# With LangChain adapter
pip install memgraph-agent[langchain]

# Everything
pip install memgraph-agent[all]
```

---

## Setup Guide

### Prerequisites

| Requirement | Notes |
|---|---|
| Python 3.11+ | `python --version` |
| Docker | For FalkorDB. [Get Docker](https://docs.docker.com/get-docker/) |
| Ollama (local) | For embeddings. [ollama.com](https://ollama.com) |
| OpenAI API key | For Graphiti entity extraction (even with local embeddings) |

### Automated setup

```bash
# Check everything
memgraph-setup

# Auto-fix: creates FalkorDB container, starts Ollama, creates .env
memgraph-setup --fix

# Run only specific checks
memgraph-setup --check Docker FalkorDB "OPENAI_API_KEY"
```

The checker validates:
- Python version ≥ 3.11
- Docker installed and daemon running
- FalkorDB container reachable (creates it if `--fix`)
- Ollama API responsive (starts `ollama serve` if `--fix`)
- `nomic-embed-text` model pulled (runs `ollama pull` if `--fix`)
- `.env` file exists with required keys (copies from `.env.example` if `--fix`)
- `OPENAI_API_KEY` is set and non-placeholder

### Manual setup

```bash
# 1. Clone
git clone https://github.com/SP3DK1D/Memomatic.git && cd Memomatic

# 2. Install
pip install -e ".[dev]"
# or with uv:
uv sync

# 3. Configure
cp .env.example .env
# edit .env — set OPENAI_API_KEY at minimum

# 4. Start FalkorDB
docker compose up -d falkordb

# 5. Pull embedding model
ollama pull nomic-embed-text

# 6. Verify
memgraph setup
```

---

## Configuration

MemGraph is configured via `config.yaml` (overridable via environment variables):

```yaml
graph:
  host: localhost
  port: 6379
  database: memgraph   # keeps data separate from other FalkorDB projects

embeddings:
  provider: ollama          # or "openai"
  model: nomic-embed-text   # or "text-embedding-3-small"
  dim: 768

retrieval:
  top_k: 20
  default_token_budget: 2000

formatter:
  default_format: claude_xml  # claude_xml | openai_system | markdown | json
```

All `config.yaml` keys can be overridden via environment variables — see [.env.example](.env.example).

---

## What's in the Box

| Module | Purpose |
|---|---|
| `memgraph.core.MemGraph` | High-level entry point: `store()`, `query()`, `forget()`, `stats()` |
| `memgraph.token_budget` | Greedy knapsack packer — the key differentiator |
| `memgraph.retrieval` | FAISS + graph hybrid search with scoring |
| `memgraph.formatter` | Claude XML / OpenAI system / Markdown / JSON output |
| `memgraph.setup_check` | Prerequisite checker + auto-installer |
| `server.app` | FastAPI REST server (`memgraph-server`) |
| `server.mcp.handler` | MCP protocol handler for Claude Code / Cursor / Windsurf |
| `adapters.GenericAgentAdapter` | Two-hook adapter for any agent framework |
| `adapters.MemGraphChatMemory` | LangChain `BaseChatMemory` drop-in |
| `adapters.MemGraphHooks` | OpenAI Agents SDK hooks |
| `adapters.SimpleOpenAIAgentAdapter` | Works with raw `openai` chat completions |
| `adapters.AdapterGenerator` | Auto-generates Node.js / TypeScript / Python adapters |
| `scanner` | Detects existing memory systems in any codebase |
| `bridge` | HTTP + IPC bridge for non-Python agents |
| `cli` | Full CLI (`memgraph setup / scan / integrate / query / store`) |

---

## Framework Adapters

### Any Python agent (3 lines)

```python
from adapters.generic import GenericAgentAdapter

adapter = GenericAgentAdapter(mg, token_budget=1500, fmt="claude_xml")

context = await adapter.before_turn(user_message)   # inject into prompt
await adapter.after_turn(messages)                   # store the turn
```

### LangChain

```python
from adapters.langchain import MemGraphChatMemory

memory = MemGraphChatMemory(mg, token_budget=1500)
chain = LLMChain(llm=chat_model, prompt=prompt, memory=memory)
# Works exactly like ConversationBufferMemory — but token-aware
```

### OpenAI Agents SDK

```python
from adapters.openai_agents import MemGraphHooks

agent = Agent(
    name="MyAgent",
    instructions="You are a helpful assistant.",
    hooks=MemGraphHooks(mg),
)
```

### Raw OpenAI completions

```python
from adapters.openai_agents import SimpleOpenAIAgentAdapter

adapter = SimpleOpenAIAgentAdapter(mg)
messages = await adapter.before_completion(messages)
response = await client.chat.completions.create(model="gpt-4o", messages=messages)
await adapter.after_completion(messages, response.choices[0].message.content)
```

### Node.js / TypeScript agents (ATLAS, OpenClaw, etc.)

```bash
# Auto-detect your agent's memory system and generate an adapter
memgraph integrate /path/to/your/agent

# Or apply it directly
memgraph integrate /path/to/your/agent --apply
```

Then add ONE line to your agent's entry point:

```js
require('./memgraph-adapter').patch();  // Node.js
// or
import './memgraph-adapter';            // TypeScript — adapter auto-patches at import
```

---

## MCP Integration (Claude Code / Cursor / Windsurf)

Run the MCP server:

```bash
memgraph-server
# or
uv run uvicorn server.app:app --port 8100
```

Add to your MCP client config:

```json
{
  "mcpServers": {
    "memgraph": {
      "url": "http://localhost:8100/mcp"
    }
  }
}
```

Tools exposed: `store_memory`, `query_memory`, `forget`, `memory_stats`, `generate_context`.

See [examples/claude_code_mcp.py](examples/claude_code_mcp.py) for a complete walkthrough.

---

## REST API

```bash
# Start server
memgraph-server   # listens on :8100

# Store a memory
curl -X POST http://localhost:8100/store \
  -H 'Content-Type: application/json' \
  -d '{"content": "Luke prefers TypeScript.", "group_id": "session-1"}'

# Query memory
curl -X POST http://localhost:8100/query \
  -H 'Content-Type: application/json' \
  -d '{"query": "What stack does Luke prefer?", "token_budget": 500}'

# Health check
curl http://localhost:8100/health
```

Interactive docs at `http://localhost:8100/docs`.

---

## CLI

```bash
# Check prerequisites
memgraph setup
memgraph setup --fix        # auto-install missing

# Scan a project's memory architecture
memgraph scan /path/to/atlas

# Generate + apply an adapter
memgraph integrate /path/to/atlas --apply

# Store and query directly
memgraph store "Luke runs Ollama on a Ryzen 5800H."
memgraph query "What hardware does Luke use?" --budget 300

# Check server health
memgraph status
```

---

## Output Formats

```python
from memgraph.formatter import OutputFormat

# Claude XML (default — Claude parses this most efficiently)
ctx = await mg.query(q, fmt=OutputFormat.CLAUDE_XML)
# → <agent_memory token_budget="1000">...</agent_memory>

# OpenAI system message
ctx = await mg.query(q, fmt=OutputFormat.OPENAI_SYSTEM)
# → [MEMORY CONTEXT] ... [/MEMORY CONTEXT]

# Markdown (for CLAUDE.md injection)
ctx = await mg.query(q, fmt=OutputFormat.MARKDOWN)
# → ## Agent Memory\n- **ATLAS**: ...

# Raw JSON
ctx = await mg.query(q, fmt=OutputFormat.JSON)
# → {"entities": [...], "facts": [...], ...}
```

---

## Roadmap

- [x] Phase 1: Core engine (FAISS + Graphiti + token budget + formatters)
- [x] Phase 2: FastAPI REST + MCP server
- [x] Phase 3: Framework adapters (LangChain, OpenAI Agents, generic), benchmarks
- [x] Phase 4: PyPI release, setup checker, CI/CD
- [ ] Hosted API tier (pay-as-you-go, no Docker required)
- [ ] LangGraph adapter
- [ ] Streaming retrieval (yield fragments as they score)
- [ ] Web dashboard (FalkorDB browser + token savings metrics)

---

## Development

```bash
# Install with dev deps
uv sync --extra dev

# Run tests (pure, no live services needed)
uv run pytest tests/ -v

# Run tests with coverage
uv run pytest tests/ --cov=memgraph --cov-report=term-missing

# Lint + format
uv run ruff check .
uv run ruff format .

# Type check
uv run mypy memgraph/

# Run benchmarks (requires live FalkorDB + Ollama)
uv run python benchmarks/token_comparison.py
uv run python benchmarks/retrieval_speed.py
uv run python benchmarks/quality_eval.py
```

### Project structure

```
memgraph/           Core Python package (store, query, forget, token budget)
server/             FastAPI REST + MCP server
adapters/           Framework adapters (LangChain, OpenAI Agents, generic, Node.js templates)
scanner/            Project scanner (detects existing memory systems)
bridge/             HTTP + IPC bridge for non-Python agents
cli/                Unified CLI (memgraph setup / scan / integrate / query)
benchmarks/         Token comparison, speed, and quality benchmarks
examples/           Working end-to-end examples
tests/              pytest suite (pure module tests, no live services)
```

---

## License

MIT — see [LICENSE](LICENSE).

---

## Credits

Built by [Luke (TechItLuke)](https://github.com/SP3DK1D) on top of:
- [Graphiti](https://github.com/getzep/graphiti) by Zep — temporal knowledge graph engine
- [FalkorDB](https://falkordb.com) — lightweight Redis-compatible graph database
- [FAISS](https://github.com/facebookresearch/faiss) by Meta — in-process vector search
- [nomic-embed-text](https://ollama.com/library/nomic-embed-text) — free local embeddings via Ollama
