Backed by embedded Kuzu, with a FastAPI ingest/query layer,
LLM chat (Ollama and Groq), and a D3 graph explorer UI.
The MemState Graph Explorer — visual topic graph, field editing, and a built-in assistant.
MemState gives AI agents a persistent, structured memory. Observations are stored as a versioned topic graph and retrieved through a small API, so agents can accumulate knowledge over time instead of relying on a fixed context window.
| Capability | Description |
|---|---|
| Topic graph storage | Versioned fields, salience, embeddings, and typed RELATED links |
| Agent API | POST /v1/ingest and POST /v1/query for observation-shaped memory operations |
| LLM assistant | Intent-routed chat with memory tools (Ollama or Groq), plus a two-phase Study pipeline for long documents |
| Graph Explorer UI | Visual topic graph, field editing, and a built-in assistant panel |
| MCP server | memstate-llm-mcp for Model Context Protocol clients |
pip install -e .
cp .env.example .env
python -m memstate.api.cli # or: memstate-api| Resource | URL |
|---|---|
| Graph Explorer | http://127.0.0.1:8765/ui/ |
| Interactive API docs | http://127.0.0.1:8765/docs |
- Python 3.11 or later
- Optional: Ollama for local LLM chat, or a Groq API key for cloud chat and speech-to-text
docker compose upSee the Docker guide for persistence and configuration.
| Guide | Description |
|---|---|
| Quickstart | Install, run, UI controls |
| Data model | Topics, fields, relationships |
| Configuration | Environment variables |
| API reference | Endpoints, request and response shapes |
| LLM providers and chat | Ollama, Groq, Study pipeline, MCP |
| Authentication | API keys and admin access |
| Docker | Container deployment |
src/memstate/ Core library, API, LLM tools, graph store
docs/ Product documentation (HTML) and repository guides (Markdown)
tests/ Pytest suite
MemState is a reference implementation of Governed Evolving Memory (GEM), the framework introduced in our paper. It is a research prototype: a runnable proof-of-concept that demonstrates how the core ideas of GEM work in practice. The system is an early, focused artifact for researchers and developers who want to explore the approach directly, and its design will continue to evolve as the framework is extended beyond this initial reference build.