Graphium

Reimagined graph memory for people who want to self-host.

Graphium is a fork of Graphiti, reworked to simplify self-hosting and reduce costs by minimizing dependencies on OpenAI, promoting Ollama as a first-class option, and making it easier to add new LLM providers.

Graphium helps AI agents remember facts, entities, and interactions over time, improving their ability to personalize user experiences.

Graphium continuously ingests episodic data, maintains bi-temporal state, and serves hybrid retrieval that combines semantic search, keyword search, and graph traversal. This fork keeps the proven architecture while stripping away hosted dependencies so you can run it with your own models on your own hardware.

What You Get

• Real-time graph construction with automatic edge invalidation and history tracking.
• A provider-agnostic LLM/embedding layer (Ollama, LiteLLM proxy, OpenAI, Anthropic, Gemini, Groq, and more).
• Fast hybrid search that combines embeddings, BM25, and neighborhood traversal.
• Optional service adapters: a REST API (FastAPI) and a Model Context Protocol (MCP) server.

Why This Fork Exists

The original project from Zep Software, Inc. is Apache 2.0 licensed but made several choices that made low‑cost self-hosting harder: it assumed an OpenAI API key, shipped telemetry wired to PostHog, linked documentation back to Zep, and included an older MCP server that lacked streamable HTTP support for homelab setups. The codebase also needed broader refactors to be easier to work with. This fork focuses on:

• Self-hosting – run against Neo4j, FalkorDB, Kuzu, or Neptune without external SaaS dependencies.
• Model choice – treat Ollama and LiteLLM-compatible providers as first-class citizens so hobbyists can control cost.
• Operational clarity – documentation for independent operators, telemetry off by default, and a licensing/NOTICE flow that credits Zep while acknowledging the divergence.

We maintain attribution in NOTICE and keep the upstream license unchanged.

Highlights & Differences

• Telemetry disabled by default; instrumentation can point at your own backend if desired.
• Provider matrix expanded with adapters for Anthropic, Gemini, Groq, Voyage, and custom LiteLLM routes.
• MCP server upgraded to FastMCP 2 transport and HTTP streaming.
• Documentation refocused on self-hosting scenarios, with step-by-step provider guides forthcoming.

If you need the original Zep-hosted experience, use the upstream repository instead of this fork.

Getting Started

• Install the core library: see docs/installation.md for requirements, extras, and concurrency tuning.
• Run the REST API: docs/server.md
• Run the MCP server: docs/mcp_setup.md (quick setup)
• Examples & notebooks: explore docs/examples/.
• Architecture & code layout: docs/design.md
• Testing: docs/testing.md

Graphium targets Python 3.12+. We recommend uv for dependency management (uv sync --all-extras).

What Changed

This fork started as a pragmatic cleanup to make Graphium friendlier to self-host outside Zep’s environment. The most significant shifts are:

• Provider abstraction overhaul – the LLM and embedding layers now sit behind a unified factory, so new providers (LiteLLM routes, Ollama-backed models, niche APIs) slot in with minimal boilerplate.
• Infrastructure decoupling – telemetry, PostHog, and SaaS-centric defaults are removed or opt-in, so a fresh checkout runs with only a graph database and your chosen model endpoints.
• Documentation + tooling pass – docs for self-hosters, trimmed automation, and a leaner CI while we rebuild coverage that doesn’t assume OpenAI accounts.
• Codebase hygiene – orchestration and search modules reorganized so tests, maintenance scripts, and future changes are easier to navigate.

Upcoming refactors will continue this trend: tighten module boundaries, add TypeDB support, and surface clearer extension points for ingest/search flows.

Project Status

Graphium remains a work in progress. Major themes on the roadmap:

1. Clarify naming across packages, images, and docs so readers recognize this as a community fork while keeping explicit attribution to Zep’s original work.
2. Expand provider documentation (LiteLLM proxy, Ollama recipes, custom factories).
3. Introduce end-to-end TypeDB support.
4. Replace the deleted testing workflow with a provider-agnostic CI pipeline.

Progress notes and TODOs live in notes.md.

Licensing

Graphium continues under the Apache License 2.0. This repository ships with a project NOTICE file crediting Zep’s original work and summarizing the changes introduced here. See docs/licensing.md for attribution guidance and contributor expectations.