memgraph-agent 0.2.0__tar.gz

memgraph_agent-0.2.0/.env.example

@@ -0,0 +1,36 @@
+# --- Required for Graphiti entity extraction ---
+OPENAI_API_KEY=sk-your-key-here
+
+# --- FalkorDB connection ---
+FALKORDB_HOST=localhost
+FALKORDB_PORT=6379
+FALKORDB_DATABASE=memgraph
+FALKORDB_USERNAME=
+FALKORDB_PASSWORD=
+
+# --- Embedding provider ---
+# "ollama" (local, free) or "openai" (cloud, paid)
+EMBEDDING_PROVIDER=ollama
+EMBEDDING_MODEL=nomic-embed-text
+EMBEDDING_DIM=768
+OLLAMA_BASE_URL=http://localhost:11434
+
+# --- LLM for Graphiti entity extraction ---
+# "openai" or "anthropic"
+LLM_PROVIDER=openai
+LLM_MODEL=gpt-4o-mini
+
+# --- MemGraph behavior ---
+DEFAULT_TOKEN_BUDGET=2000
+MEMGRAPH_LOG_LEVEL=INFO
+MEMGRAPH_API_PORT=8100
+MEMGRAPH_API_HOST=0.0.0.0
+
+# --- Scoring weights (must sum to 1.0) ---
+SCORE_WEIGHT_SEMANTIC=0.5
+SCORE_WEIGHT_RECENCY=0.3
+SCORE_WEIGHT_CENTRALITY=0.2
+RECENCY_DECAY_DAYS=30
+
+# --- Telemetry ---
+GRAPHITI_TELEMETRY_ENABLED=false

memgraph_agent-0.2.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.env
+.env.local
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.log
+.DS_Store
+.idea/
+.vscode/
+# Graphify knowledge graph
+graphify-out/
+.graphifyignore

memgraph_agent-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luke (TechItLuke)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memgraph_agent-0.2.0/PKG-INFO

@@ -0,0 +1,525 @@
+Metadata-Version: 2.4
+Name: memgraph-agent
+Version: 0.2.0
+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