MemMachine: A Memory Layer That Separates Agent State from the Model

What MemMachine Actually Stores and Why That Matters

The README describes three memory types. Episodic memory is conversational context stored in a graph database, Neo4j. Profile memory is long-term user facts stored in SQL. Working memory is short-term context for the current session. The split is not cosmetic. Each type has a different retention and retrieval pattern, and each uses a different storage engine. That means an agent can recall a user's stated preference from a month ago while also keeping the current conversation's temporary state separate. For developers, the practical consequence is that you do not have to design a single schema that tries to serve both long-term facts and session scratch space. The graph structure for episodic memory is meant to capture relationships between conversation events, which a flat table would handle poorly. The README's example shows a memory.add call returning a uid, and a search returning an episode with content. That suggests the server indexes content and retrieves by relevance, but the exact retrieval mechanism is not documented in the material. What is clear is that the project positions itself as a universal layer, meaning the same memory instance can be shared across different agents and models, as long as they speak the same API.

The Client-Server Split and the Five-Line Setup

MemMachine is not a library you import and call in-process. It requires a running server. The quick start begins with pip install memmachine-client, then initializes a client pointing at base_url=http://localhost:8080. That implies you must first start the server, either locally or via the hosted platform. The README gives a five-line example: create a client, get or create a project, create a memory instance with group_id, agent_id, user_id, and session_id, then call memory.add and memory.search. The group_id and agent_id parameters suggest a hierarchy where one project can contain multiple agents and user sessions. The search result is nested deeply: results.content.episodic_memory.long_term_memory.episodes[0].content. That path tells you the response object is structured, not a flat string. The setup is genuinely short, but the dependency on a server is a real operational cost. You are not just adding a pip package; you are deploying a service. The README points to Docker and self-hosted options, but does not give the exact docker run command. So the five lines are only the client half.

Storage Engines: Graph for Episodic, SQL for Profiles

The architecture section says episodic memory is stored in a graph database and profile memory in SQL. The README names Neo4j as the graph database for episodic memory. This is a deliberate design choice. Graph storage suits conversational context because episodes are linked by entities, time, and causality. A relational table would make it harder to traverse from one conversation to a related fact. Profile memory, in contrast, is a set of stable user attributes, which fits SQL's structured rows. The trade-off is that you now need to operate two storage systems. Neo4j is a heavyweight dependency compared to a simple vector store or a single Postgres instance. The README does not say whether you can swap the graph database for another, nor does it specify the SQL engine. That lack of detail matters for teams that want to run MemMachine in a constrained environment. The project claims flexible storage, but the material only shows one graph option. If you already run Postgres and do not want Neo4j, you have no confirmation from this README that you can avoid it.

Integrations: Framework Adapters and the MCP Server

The README lists eight integrations: LangChain, LangGraph, CrewAI, LlamaIndex, AWS Strands Agent SDK, n8n, Dify, and FastGPT. Each has a directory under integrations in the repository. That breadth is the project's main argument for being universal. Instead of writing a custom memory class for each framework, you use a provider that wraps the MemMachine client. The AWS Strands topic in the repository topics confirms a focus on that SDK. The MCP server support is notable. The README shows two commands: memmachine-mcp-stdio for Claude Desktop and memmachine-mcp-http for web clients. MCP is a standard that lets any MCP-compatible client talk to the memory server. That is a different integration path than a framework-specific adapter. For a developer, this means you can use MemMachine with a tool like Cursor without writing Python code, as long as the MCP client can launch the stdio or HTTP server. The README does not specify which MCP version or what capabilities the server exposes, so you would need to check the docs. The existence of both framework adapters and an MCP server suggests the team is trying to cover both the library approach and the protocol approach.

Who Should Not Use It: The Wrong Tool Cases

MemMachine is not a good fit for a simple chatbot that only needs to remember the last message. That is what working memory is for, but the README does not show a lightweight in-process mode. You must run a server and likely a graph database. For a small prototype or a single-script agent, that is heavy. The README also does not mention any vector search for semantic similarity. The search example is a natural language query, but the underlying mechanism could be keyword-based or embedding-based. The material does not say. If your use case requires similarity search over unstructured text with embeddings, you cannot confirm MemMachine supports it from this README. Another wrong-tool case is when you need memory to be tightly coupled to a specific model's context window, like a sliding window of recent tokens. MemMachine's episodic memory is long-term and graph-based, not a token buffer. The project also assumes you are comfortable with the client-server model and the operational burden of the server. For a team that wants zero infrastructure, a cloud-hosted option exists, but the README only says you can create a free account on the MemMachine Platform. It does not give pricing or data residency details.

A Real Alternative: LangGraph's Built-in Checkpointer

LangGraph, which is one of the listed integrations, offers its own persistence mechanism through checkpointer. That is a different approach. LangGraph's built-in state management stores the full graph state at each step, using a checkpointer that can be backed by SQLite or Postgres. MemMachine, by contrast, is an external memory service that you call from an agent. The difference is architectural. With LangGraph's checkpointer, you get exact state restoration for a specific graph run, but that state is tied to that graph's schema. With MemMachine, you get a generic memory API that can be shared across different agents and frameworks. So if you are only using LangGraph and need state persistence, you might not need MemMachine at all. If you have multiple frameworks or want a unified memory store that outlives any single graph, MemMachine becomes relevant. The README's LangGraph integration presumably adapts MemMachine to LangGraph's memory interface, but the README does not explain how the two interact. That is a gap you would need to investigate before choosing.

Maintenance, Licensing, and Upgrade Considerations

The project is licensed under Apache-2.0, which is permissive for commercial use, but you should read the full license text for any attribution requirements. The repository is active, with recent releases v0.3.9 in May 2026 and v0.3.8 and v0.3.7 in the same month. That cadence suggests ongoing fixes, but it also means the API could change between minor versions. The quick start example uses from memmachine_client import import MemMachineClient, which looks like a typo in the README. The correct syntax is likely from memmachine_client import MemMachineClient. That error is a red flag for documentation quality. If the README has a syntax error in the central example, you should expect friction elsewhere. The project also depends on Neo4j, which has its own version and maintenance burden. Upgrading MemMachine may require upgrading Neo4j or the client SDK. The README does not provide a migration guide or a changelog link. Before adopting, you should check the release notes on GitHub for any breaking changes between v0.3.7 and v0.3.9. The last push to the main branch was September 2026, after the latest release, so there may be unreleased changes on the default branch.

Editorial conclusion

Adopt MemMachine if you are building agents in LangChain, LangGraph, CrewAI, or LlamaIndex and need cross-session memory without writing your own graph and SQL storage. Skip it if you only need a simple key-value cache or if your stack is not Python-based, since the primary SDK is Python. Before adopting, verify that the server's Neo4j and SQL requirements fit your deployment, check the exact API for memory.add and search in the current docs, and confirm the MCP server works with your specific client, as the README does not specify version compatibility.

Official sources

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