MemMachine: a long-term memory layer for AI agents, and what it costs to run it

The statelessness problem MemMachine is aimed at

Most agent frameworks give you a conversation buffer and nothing else. The buffer dies with the process. If you want an assistant to remember that a user prefers aisle seats, you end up writing your own table, your own retrieval query and your own prompt injection step, and then you maintain that forever.

MemMachine's pitch is that this belongs in a separate layer. The README frames it as transforming stateless chatbots into personalized, context-aware assistants, and it names three memory types: working memory for the current session, episodic memory for conversational context that persists across sessions, and profile memory for long-term user facts and preferences. The target reader is a developer building an agent, a researcher experimenting with agent architectures, or a team that needs cross-session memory in an LLM application. The README also lists eight framework integrations, including LangChain, LangGraph, CrewAI, LlamaIndex, AWS Strands and n8n, which tells you the intended adoption path is as a drop-in memory provider rather than a framework of its own.

How the episodic and profile split actually works

The architecture section describes three layers. Agents reach MemMachine through the API layer: a RESTful API, a Python SDK, or an MCP server. MemMachine then processes each interaction and writes it into two stores with different shapes. Episodic memory, meaning conversational context, goes into a graph database. Profile memory, meaning long-term user facts, goes into SQL.

The docker-compose.yml in the repository makes the concrete choice visible: Neo4j 5.23-community for the graph side, with the apoc and graph-data-science plugins enabled, and pgvector/pgvector:pg16 for the SQL side. That pairing is the design statement. Conversation history is a network of related events, so it lives in a graph. User facts are records you look up by key, so they live in a relational table with a vector extension for semantic lookup.

The client mirrors this. A memory object is scoped by group_id, agent_id, user_id and session_id, and a search returns a nested result where episodic results appear under content.episodic_memory.long_term_memory.episodes. That nesting is verbose, but it is honest about the fact that you are querying more than one store. The README also claims memory survives restarts, sessions and model changes, which follows from memory living outside the agent process rather than in its context window.

Installing the client and adding your first memory

The README states a prerequisite plainly: the client code requires a running MemMachine server. You either start one locally following the quickstart guide, or create an account on the MemMachine Platform. The client itself is a single pip install.

pip install memmachine-client

The README's example then initializes a client against a local server on port 8080, gets or creates a project, and opens a memory scoped to one user and one session.

from memmachine_client import MemMachineClient

client = MemMachineClient(base_url="http://localhost:8080")
project = client.get_or_create_project(org_id="my_org", project_id="my_project")
memory = project.memory(
    group_id="default",
    agent_id="travel_agent",
    user_id="alice",
    session_id="session_001"
)

Writing and reading back is two calls. Note that the import line in the README reads `from memmachine_client import import MemMachineClient`, which is a typo in the documentation; the correct form is the one shown above. The add call takes an optional metadata dictionary, and search returns a nested result object.

memory.add("I prefer aisle seats on flights", metadata={"category": "travel"})
results = memory.search("What are my flight preferences?")
print(results.content.episodic_memory.long_term_memory.episodes[0].content)

If you would rather not run the server yourself, the repository ships a docker-compose.yml that starts Postgres with pgvector and Neo4j together, and a memmachine-compose.sh script alongside it. The compose file defaults Postgres to port 5432 and Neo4j Bolt to 7687, with Neo4j HTTP on 7474, all overridable through environment variables such as POSTGRES_PORT and NEO4J_PORT.

The Neo4j dependency is the real adoption cost

Two databases is not a small ask. A team that wanted persistent agent memory now operates Postgres and Neo4j, and the compose file shows Neo4j configured with a 512 MB initial heap and a 1 GB maximum, plus a Bolt thread pool raised to 2000. Those are settings someone tuned for a workload, and you inherit them as defaults.

The optional retrieval path adds another dependency with a sharper edge. The pyproject.toml defines a multihop dependency group containing spaCy and the en_core_web_sm model, described in a comment as the non-LLM multi-hop decomposer. The same comment explains why it is not a hard runtime dependency: spaCy model wheels are not on PyPI so pip cannot resolve them, and spaCy 3.8.x has no cp314 wheels. When spaCy is absent, RaragQueryAgent falls back to LLM-based query splitting. So on Python 3.14 the group is skipped entirely, and query decomposition costs you LLM calls instead of local model inference. That is a real trade-off between latency, cost and Python version, and the repository documents it more clearly than the README does.

The README does not document backup, restore or migration procedures for either store. The presence of alembic.ini at the top level suggests schema migrations for the SQL side are handled with Alembic, but the README is silent on how graph data is versioned or exported. Before putting user facts into this system, that gap is worth resolving against the docs directory rather than assuming it is covered.

Where MemMachine is the wrong tool

If your agent only needs the current conversation, this is overkill. A context buffer and a summarization step cover that case with no infrastructure. MemMachine earns its keep when memory must outlive the process and the model.

It is also the wrong choice if you cannot run Neo4j. There is no embedded mode described in the README: episodic memory is stored in a graph database, full stop. Teams on serverless platforms or in environments where a Bolt connection is not available will find the client useless without a reachable server.

Finally, the README's quickstart presents the client as a five-line change, and that framing hides the operational half. The five lines assume a server is already running somewhere. Budget for the server, the two databases, and the LLM provider used for whatever extraction and query decomposition happens inside MemMachine, because the project is described as LLM agnostic and works with OpenAI, Anthropic, Bedrock and Ollama, which means you supply one.

MemMachine against Mem0 and plain vector stores

The comparison people reach for is Mem0, which appears in the related searches around this project. The architectural difference is the memory model. A typical Mem0-style setup extracts facts from a conversation and stores them as embeddings in a vector store, so retrieval is similarity search over a flat set of memories. MemMachine keeps two stores with different semantics: a graph for episodic conversation and SQL for profile facts. That means a query can traverse conversational relationships in Neo4j while profile lookups stay as ordinary relational reads, and the two are merged in the response object.

The cost of that design is the one described above: more services to run, and a result shape that forces you to know which store answered. A single vector store is easier to operate and easier to reason about. A graph is better when the relationships between events matter more than the text of any single event. Neither is universally right, and MemMachine's choice is a bet that agent memory looks more like a knowledge graph than a pile of embeddings. The repository's topics include knowledge-graph, which confirms that is the intended direction.

For teams already standardized on LangChain or LangGraph memory abstractions, the integrations directory is the lower-friction path than calling the client directly, since the memory provider interface is already wired for those frameworks.

Licence, releases and what upgrading looks like

MemMachine is Apache-2.0, which permits commercial use and modification with the usual attribution and notice requirements, and includes a patent grant. That is a permissive licence, and it is the same family as most of the agent tooling it integrates with. It is not legal advice; if you redistribute the server, read the LICENSE file and the NOTICE handling your own counsel requires.

The release cadence visible in the repository is three releases in May 2026: v0.3.7 on 2026-05-01, v0.3.8 on 2026-05-08, and v0.3.9 on 2026-05-18. The last push to the default branch was on 2026-09-09, so the repository is not archived and the branch has moved since the last tagged release. That gap between the newest tag and the newest commit is normal for a project of this shape, but it means pinning to a release tag and pinning to main are different things. The pyproject.toml declares a uv workspace with three members (packages/client, packages/common, packages/server) and a constraint-dependencies list that pins minimum versions for transitive packages including authlib, cryptography, PyJWT and transformers. Those constraints exist for a reason, and a downstream project that resolves its own versions of those libraries can end up outside the tested set.

The upgrade cost that matters most is the server, not the client. The Dockerfile builds memmachine-server in a two-stage image on python:3.12-slim-trixie and supports a GPU build argument that swaps in an extra dependency set. If you self-host, your upgrade is a container rebuild plus whatever Alembic migrations the SQL side requires. The README does not describe a rollback path, so treat the version of the server and the version of memmachine-client as a pair you test together.

Editorial conclusion

Adopt MemMachine if you already run Neo4j and Postgres, or are willing to run both via the repository's docker-compose.yml, and you want cross-session recall that survives a model swap. Do not adopt it if you want a single embedded store with no external services, or if you need a documented backup and restore path before you ship. Verify first that the server image and the memmachine-client release you install are version-compatible, and that your Python version is below 3.14 if you intend to use the optional spaCy multi-hop decomposer.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. MemMachine/MemMachine on GitHub
3. Project website
4. README
5. Releases