# https://github.com/MemMachine/MemMachine Project Manual

Generated at: 2026-07-05 23:05:08 UTC

## Table of Contents

- [MemMachine Overview & System Architecture](#page-overview)
- [Memory Architecture: Episodic, Profile/Semantic, and Working Memory](#page-memory)
- [Storage Backends: Vector Stores, Graph Databases, and Episode Persistence](#page-storage)
- [SDKs, REST API, MCP, and Framework Integrations](#page-developer)

<a id='page-overview'></a>

## MemMachine Overview & System Architecture

### Related Pages

Related topics: [Memory Architecture: Episodic, Profile/Semantic, and Working Memory](#page-memory), [Storage Backends: Vector Stores, Graph Databases, and Episode Persistence](#page-storage), [SDKs, REST API, MCP, and Framework Integrations](#page-developer)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/MemMachine/MemMachine/blob/main/README.md)
- [USAGE.md](https://github.com/MemMachine/MemMachine/blob/main/USAGE.md)
- [pyproject.toml](https://github.com/MemMachine/MemMachine/blob/main/pyproject.toml)
- [docker-compose.yml](https://github.com/MemMachine/MemMachine/blob/main/docker-compose.yml)
- [docs/getting_started/introduction.mdx](https://github.com/MemMachine/MemMachine/blob/main/docs/getting_started/introduction.mdx)
- [docs/core_concepts/agentic_memory.mdx](https://github.com/MemMachine/MemMachine/blob/main/docs/core_concepts/agentic_memory.mdx)
</details>

# MemMachine Overview & System Architecture

MemMachine is an event-backed long-term memory layer designed to give LLM-driven agents persistent, structured recall across sessions. It exposes a server, Python and TypeScript clients, and integrations with frameworks such as Strands Agents, while keeping storage pluggable behind vector-store and graph-store abstractions. Source: [README.md:1-40]()

## Purpose and Scope

The project addresses two recurring pain points for agent developers: stateless conversations and bespoke memory glue code. MemMachine accepts conversational messages, episodes, or arbitrary memory payloads, transforms them through an LLM-assisted ingestion pipeline, and persists the results so future `search` calls can return both raw episodic context and distilled semantic facts. Source: [docs/getting_started/introduction.mdx:1-60]()

The system is delivered as:

- A Python server package (`memmachine-server`) exposing an HTTP API.
- A Python client (`memmachine-client`) used by application code.
- A TypeScript client (`memmachine-ts-client`) for Node and browser integrations.
- Optional integrations, e.g. `strands-memmachine`, that bridge external agent frameworks. Source: [pyproject.toml:1-80]()

Docker assets (`docker-compose.yml`) wire the server together with PostgreSQL, Neo4j, and a vector store so the full stack can run locally for development. Source: [docker-compose.yml:1-60]()

## Core Memory Model

MemMachine organises stored content into two cooperating stores:

| Memory type | Backing store | Purpose |
|---|---|---|
| Episodic memory | Graph database (Neo4j by default) | Captures conversation turns, events, and their relationships so the server can reconstruct temporal or relational context. |
| Semantic memory | Vector store (Qdrant or embedded SQLite) | Holds derived facts, features, and citation links back to the episodes they were extracted from. |

Source: [docs/core_concepts/agentic_memory.mdx:1-90]()

Ingestion writes to both stores. The semantic pipeline calls an LLM to extract structured features from each episode, persists them as embeddings in the vector store, and records citations pointing back to the originating episodes in the graph. A `search` call returns the combined view: episodic context plus the distilled semantic memory field. Source: [USAGE.md:1-120]()

## System Architecture

```mermaid
flowchart LR
    Client[Client / Agent SDK] -->|HTTP| API[MemMachine Server]
    API --> EpisodicIngest[Episodic Ingestion]
    API --> SemanticIngest[Semantic Ingestion]
    EpisodicIngest --> Graph[(Graph Store<br/>Neo4j)]
    SemanticIngest --> LLM[LLM Provider]
    LLM --> Vector[(Vector Store<br/>Qdrant / SQLite)]
    SemanticIngest --> Vector
    SemanticIngest --> Graph
    API -->|search response| Client
```

The server is the single entry point. Requests are dispatched to ingestion workers that write to the graph and vector backends, and to a query path that fans out to both stores before merging results. Source: [USAGE.md:40-140]()

The `VectorStore` abstraction (referenced in feature request #1470) currently ships with Qdrant and embedded SQLite implementations; Milvus is being added as a third option, and users have asked for Zilliz Cloud and Milvus Lite support. Source: [README.md:60-120]()

## Storage Backends and Configuration

Because episodic and semantic stores are independent, operators can mix and match. The default `docker-compose.yml` provisions Neo4j for episodic memory and a vector store for semantic memory, but the same server binary can target an alternative graph database. Feature request #1324 proposes Apache AGE as a GPL-friendly alternative to Neo4j, which is the main reason backend flexibility matters. Source: [docker-compose.yml:20-90]()

Configuration is driven by environment variables and a YAML config consumed by the server at startup. The vector store selection, embedding model, LLM credentials, and graph-store connection string are all declared there; no code changes are required to swap backends once a backend implements the interface. Source: [USAGE.md:60-180]()

## Known Issues and Community Discussion

Several open issues highlight ongoing architectural work:

- **Semantic ingestion dead loop (#1270):** When the LLM returns an invalid response during semantic ingestion, the ingestion step can be retried indefinitely, wasting tokens until the failure is detected upstream.
- **Missing semantic results in client search (#690):** `MemMachineClient.search` may return an empty `semantic_memory` field even when episodic memory is populated, suggesting gaps in the client-side merge logic.
- **Semantic message duplication (#640):** Duplicate episodes can cause the same semantic feature to be re-ingested and re-cited, inflating storage and citation counts.
- **SQLiteVectorStore race (#1468):** In the embedded SQLite backend, a `delete()` racing an `upsert()` on the same collection can silently drop the new vector because SQLite reuses the deleted row's id.

These issues underline two architectural themes: ingestion must be idempotent and retry-safe, and the abstraction between episodic and semantic stores must be enforced by the client as well as the server. Source: [docs/core_concepts/agentic_memory.mdx:90-160]()

The latest tagged release, v0.3.9, focuses on documentation clarity (filter prefixes, package readmes, client install instructions) and on the embedded vector-store implementations introduced in v0.3.8, indicating that backend portability and developer ergonomics are the current priorities for the project. Source: [README.md:40-100]()

---

<a id='page-memory'></a>

## Memory Architecture: Episodic, Profile/Semantic, and Working Memory

### Related Pages

Related topics: [MemMachine Overview & System Architecture](#page-overview), [Storage Backends: Vector Stores, Graph Databases, and Episode Persistence](#page-storage)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/server/src/memmachine_server/episodic_memory/episodic_memory.py](https://github.com/MemMachine/MemMachine/blob/main/packages/server/src/memmachine_server/episodic_memory/episodic_memory.py)
- [packages/server/src/memmachine_server/episodic_memory/episodic_memory_manager.py](https://github.com/MemMachine/MemMachine/blob/main/packages/server/src/memmachine_server/episodic_memory/episodic_memory_manager.py)
- [packages/server/src/memmachine_server/episodic_memory/long_term_memory/long_term_memory.py](https://github.com/MemMachine/MemMachine/blob/main/packages/server/src/memmachine_server/episodic_memory/long_term_memory/long_term_memory.py)
- [packages/server/src/memmachine_server/episodic_memory/short_term_memory/short_term_memory.py](https://github.com/MemMachine/MemMachine/blob/main/packages/server/src/memmachine_server/episodic_memory/short_term_memory/short_term_memory.py)
- [packages/server/src/memmachine_server/episodic_memory/declarative_memory/declarative_memory.py](https://github.com/MemMachine/MemMachine/blob/main/packages/server/src/memmachine_server/episodic_memory/declarative_memory/declarative_memory.py)
- [packages/server/src/memmachine_server/semantic_memory/semantic_memory.py](https://github.com/MemMachine/MemMachine/blob/main/packages/server/src/memmachine_server/semantic_memory/semantic_memory.py)
</details>

# Memory Architecture: Episodic, Profile/Semantic, and Working Memory

## Overview

MemMachine organizes agent memory into three complementary stores that together support context-aware, personalized LLM interactions. The system splits memory along two axes: **temporal horizon** (working short-term vs. cross-session long-term) and **content type** (raw episodic events vs. distilled profile features). The orchestrator that ties these together is `EpisodicMemoryManager`, exposed to the rest of the server via the `EpisodicMemory` facade. `SemanticMemory` runs as a sibling service that derives structured profile statements from episode content.

This layered architecture lets MemMachine keep recent conversation tokens cheap (working memory), preserve the full event history of past sessions graph-fashion (episodic long-term memory), and continuously extract durable facts about the user (semantic/profile memory) that an application can read like a knowledge base.

## The Three Memory Stores

### Episodic Memory — Long-Term Event Log

Long-term memory is implemented as an event-backed graph. Every message ingested by the system is stored as an `episode` node linked to a `person` (agent) and a `session`, and may carry typed edges such as `MENTIONS` or `REFERENCES` to other nodes (entities, features, other episodes). Storage is delegated to pluggable backends selected at construction time — `Neo4jEpisodicMemoryStore` is the default, and the community is actively evaluating `Apache AGE` as a GPL-friendly alternative (`Source: [packages/server/src/memmachine_server/episodic_memory/long_term_memory/long_term_memory.py]()`).

The public surface is the `LongTermMemory` class, which owns the full CRUD lifecycle:

| Operation | Purpose |
|---|---|
| `add_episode` | Persists a new episode node with embeddings and metadata, optionally linking to a declarative feature |
| `get_episode` | Retrieves one episode by id |
| `search_episodes` | Vector-similarity retrieval combined with graph traversal and feature/property filters |
| `delete_episode` | Removes an episode and its incident edges |
| `add_person / get_person` | Manages the actor node that anchors episodes to a user or agent |

`LongTermMemory` exposes a `search` method that returns ranked `(episode, relevance_score)` pairs, optionally narrowed by a `tag_match` expression. The store layer splits persistence (`EpisodicMemoryStorage`) from retrieval logic so that vector indexes, graph queries, and ranking can evolve independently (`Source: [packages/server/src/memmachine_server/episodic_memory/long_term_memory/long_term_memory.py]()`).

### Semantic / Profile Memory — Distilled Features

`SemanticMemory` is the distilled store. It consumes episodes and produces declarative *features* — structured facts such as `My name is Christian`. Each feature carries a `tag` (e.g. `user.name`), `value`, and a back-reference list of episodes that cited it. Features live in a relational store (SQLite-backed by default) while their vector embeddings are kept in a `VectorStore` backend.

The ingestion pipeline is asynchronous and LLM-driven:

1. New episodes are buffered; a background task (`_full_msg_ingestion_worker`) pulls batches.
2. An LLM extracts `(tag, value, citation_episode_ids)` triples from the batch.
3. The same worker upserts features into the declarative store and the vector store, updating citation counts.
4. A feature merge step deduplicates near-duplicates using a similarity threshold, which directly mitigates the "semantic duplication" failure mode reported in Issue #640 (`Source: [packages/server/src/memmachine_server/semantic_memory/semantic_memory.py]()`).

`SemanticMemory` exposes `search(query)`, `get_feature(tag)`, and listing helpers. Critically, this store is the one the `MemMachineClient.search` call should populate but historically returned empty — see Issue #690, a known gap between server-side ingestion and the client's response shape (`Source: [packages/server/src/memmachine_server/semantic_memory/semantic_memory.py]()`).

### Working / Short-Term Memory — In-Context Buffer

Short-term memory is the cheapest tier. `ShortTermMemory` keeps a bounded, in-memory deque of recent messages per session plus lightweight counters used by the manager for cache pressure. Its responsibilities are deliberately narrow:

- Provide O(1) `add_message` / `get_messages` for the active session window.
- Expose a `recent_count` signal that the manager uses to decide when to overflow into long-term memory.
- Survive only for the lifetime of the process — durability is the long-term store's job.

Because it carries no graph or vector state, there is no separate backend; the class is a thin orchestrator helper (`Source: [packages/server/src/memmachine_server/episodic_memory/short_term_memory/short_term_memory.py]()`).

## Orchestration: How the Manager Coordinates Them

`EpisodicMemory` is the public facade. A typical request flow looks like this:

```mermaid
flowchart LR
    A[Client message] --> B[EpisodicMemory.add_episode]
    B --> C[ShortTermMemory.add_message]
    B --> D[LongTermMemory.add_episode]
    D --> E[(Graph store + Vector index)]
    D --> F[SemanticMemory ingest task]
    F --> G[(Features table + Vector store)]
    H[Client search] --> I[EpisodicMemory.search]
    I --> D
    H --> J[SemanticMemory.search]
```

`EpisodicMemoryManager` handles the spillover policy: as `ShortTermMemory.recent_count` exceeds a configured threshold, older messages are flushed through `add_episode` so the graph store stays the source of truth. Declarative memory is layered on top of the same episodes — when a feature is extracted, `declarative_memory` records the cross-reference from feature back to the episode(s) that justify it (`Source: [packages/server/src/memmachine_server/episodic_memory/episodic_memory_manager.py]()`).

`DeclarativeMemory` is a thin coordination class that owns the feature↔episode citation table and provides `add_feature`, `update_feature`, and `delete_feature`. Combined with the `VectorStore` abstraction (currently Qdrant- and SQLite-backed; Milvus and AGE are tracked as upcoming backends in Issues #1470 and #1324), it forms the durable profile layer (`Source: [packages/server/src/memmachine_server/episodic_memory/declarative_memory/declarative_memory.py]()`).

## Operational Considerations and Known Gaps

- **Backend flexibility.** The episodic long-term store is pluggable; users running commercial stacks have hit the GPL license of Neo4j Community Edition, driving the AGE proposal (#1324). Similarly, the vector-store abstraction is being extended with Milvus (#1470).
- **Concurrency hazards.** Issue #1468 documents a row-id reuse race in `SQLiteVectorStore` that can silently drop vectors when a `delete()` races an `upsert()` on the same collection — relevant for any deployment using the embedded SQLite vector backend for either long-term episode embeddings or semantic feature embeddings.
- **Ingestion liveness.** Issue #1270 reports that an invalid LLM response during semantic ingestion can cause a retry loop in `semantic_ingestion`, wasting tokens. Operators should monitor the ingestion worker and bound retry attempts in configuration.
- **Read path correctness.** Issue #690 confirms that, despite the feature store being populated, the client `search` response can still return `semantic_memory: []`. This is a known divergence between server state and client serialization that should be checked when debugging retrieval.

## Summary

MemMachine's memory architecture is a three-tier stack: `ShortTermMemory` (in-context recent messages) → `LongTermMemory` (graph-backed episodes with vector retrieval) → `SemanticMemory` (LLM-distilled profile features). The `EpisodicMemory` facade and `EpisodicMemoryManager` orchestrate the flow, while `DeclarativeMemory` and the `VectorStore` abstraction keep feature provenance and similarity search swappable. Each tier can be reasoned about and scaled independently, which is what makes the project a foundation for long-lived agent memory rather than a single chat log.

---

<a id='page-storage'></a>

## Storage Backends: Vector Stores, Graph Databases, and Episode Persistence

### Related Pages

Related topics: [Memory Architecture: Episodic, Profile/Semantic, and Working Memory](#page-memory), [MemMachine Overview & System Architecture](#page-overview)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/server/src/memmachine_server/common/vector_store/vector_store.py](https://github.com/MemMachine/MemMachine/blob/main/packages/server/src/memmachine_server/common/vector_store/vector_store.py)
- [packages/server/src/memmachine_server/common/vector_store/sqlite_vector_store.py](https://github.com/MemMachine/MemMachine/blob/main/packages/server/src/memmachine_server/common/vector_store/sqlite_vector_store.py)
- [packages/server/src/memmachine_server/common/vector_store/sqlite_vec_vector_store.py](https://github.com/MemMachine/MemMachine/blob/main/packages/server/src/memmachine_server/common/vector_store/sqlite_vec_vector_store.py)
- [packages/server/src/memmachine_server/common/vector_store/qdrant_vector_store.py](https://github.com/MemMachine/MemMachine/blob/main/packages/server/src/memmachine_server/common/vector_store/qdrant_vector_store.py)
- [packages/server/src/memmachine_server/common/vector_store/vector_search_engine/hnswlib_engine.py](https://github.com/MemMachine/MemMachine/blob/main/packages/server/src/memmachine_server/common/vector_store/vector_search_engine/hnswlib_engine.py)
- [packages/server/src/memmachine_server/common/vector_store/vector_search_engine/usearch_engine.py](https://github.com/MemMachine/MemMachine/blob/main/packages/server/src/memmachine_server/common/vector_store/vector_search_engine/usearch_engine.py)
- [packages/server/src/memmachine_server/semantic_memory/semantic_ingestion.py](https://github.com/MemMachine/MemMachine/blob/main/packages/server/src/memmachine_server/semantic_memory/semantic_ingestion.py)
</details>

# Storage Backends: Vector Stores, Graph Databases, and Episode Persistence

MemMachine's long-term memory system relies on a layered storage architecture that separates vector similarity search from graph-based episodic context and from raw episode persistence. This page documents the abstractions and concrete backends that make up that layer, as found in `packages/server/src/memmachine_server`.

## 1. Purpose and Scope of the Storage Layer

The storage layer is responsible for three concerns:

- **Vector storage and similarity search** for embedding-based recall (semantic memory).
- **Graph storage** for episodic memory, where episodes, features, and citations are linked as nodes and edges.
- **Episode persistence** for the raw, append-only message log that feeds downstream summarisation and ingestion pipelines.

These concerns are kept behind narrow interfaces so that operators can swap implementations without touching the rest of the server. As of the v0.3.9 release, embedded vector stores (SQLite-backed) were added to simplify local deployments, and a Qdrant-backed option remains the recommended production-grade path. Source: [vector_store.py:1-40]()

Community requests tracked in issues #1470 (Milvus backend) and #1324 (Apache AGE as a Neo4j alternative) confirm that the abstraction is expected to remain pluggable as the ecosystem of supported backends grows.

## 2. Vector Store Abstraction and Backends

### 2.1 The `VectorStore` interface

The `VectorStore` abstract base class defines the contract that every vector backend must implement: collection-scoped `upsert`, `delete`, `search`, and metadata filtering. Callers receive scored records carrying both the embedding and the originating payload, allowing the rest of the system to treat storage as opaque similarity search. Source: [vector_store.py:1-120]()

### 2.2 SQLite-backed stores

`SQLiteVectorStore` and `SQLiteVecVectorStore` provide zero-dependency local persistence. They store dense vectors in a relational table and optionally delegate approximate nearest-neighbor search to the bundled in-process engines. Community issue #1468 documents a known race condition where `delete()` racing an `upsert()` on the same collection can silently lose an upserted vector when SQLite reuses the deleted row's `row_id`. Users who need concurrent async writes should serialise operations on a per-collection basis or migrate to an external backend. Source: [sqlite_vector_store.py:1-180](), [sqlite_vec_vector_store.py:1-160]()

### 2.3 External backend: Qdrant

`QdrantVectorStore` wraps a Qdrant client and is the recommended option for multi-node deployments. It supports payload-based filtering, HNSW index configuration, and scale-out replicas. Source: [qdrant_vector_store.py:1-200]()

### 2.4 Vector search engines

Two pluggable ANN engines ship with the project:

- `HnswlibEngine` — a hierarchical navigable small-world graph implementation suitable for in-process search across millions of vectors.
- `USearchEngine` — a leaner alternative optimised for lower memory footprints.

Each engine implements a common interface so that `SQLiteVecVectorStore` can choose one at startup via configuration. Source: [hnswlib_engine.py:1-160](), [usearch_engine.py:1-140]()

```mermaid
flowchart LR
  Client --> Ingest[Semantic Ingestion]
  Ingest --> Embed[Embedder]
  Embed --> VS{{VectorStore}}
  VS --> SQLite[SQLite / sqlite-vec]
  VS --> Qdrant[Qdrant]
  SQLite --> HNSW[Hnswlib / USearch]
  VS --> Graph[(Graph DB - Episodic)]
  VS --> Episode[(Episode Store)]
```

## 3. Graph Database for Episodic Memory

Episodes are not flat: each `Feature` (a derived semantic fact) is linked back to the `Episode` rows that produced it via a citation table, and adjacent episodes share temporal edges. MemMachine uses a graph database to traverse these relationships during recall. Neo4j Community Edition is the default driver, but its GPLv3 licence is a blocker for some vendored deployments — community issue #1324 proposes Apache AGE as a drop-in alternative so that MemMachine can be shipped inside Apache-licensed distributions. Source: [semantic_ingestion.py:1-220]()

Graph traversal is invoked whenever the system needs to expand a recalled feature back to its source context, so the choice of backend has a direct impact on retrieval quality and latency.

## 4. Episode Persistence

Episodes are the immutable source of truth. The episode store is append-only: every message or tool call that enters MemMachine is written here first, and downstream components (semantic ingestion, episodic recall, summarisation) read from it. This ordering is what enables the dead-loop bug discussed in issue #1270, where invalid LLM responses can repeatedly re-trigger `semantic_ingestion` against the same pending episode. Source: [semantic_ingestion.py:80-180]()

Two operational behaviours follow from the append-only design:

1. **Duplicate handling is upstream of the store.** Issue #640 documents semantic duplication caused by re-ingesting the same episode; deduplication must occur at the producer boundary before writes hit the store.
2. **Recency is derived, not stored.** Recency scoring is computed from the episode timestamp plus the graph distance, not maintained as a separate index.

## 5. Configuration and Operational Notes

- Filter prefixes must be configured consistently across backends; PR #1352 (v0.3.9) clarified the required prefix syntax so that SQLite and Qdrant interpret filters identically. Source: [vector_store.py:60-120]()
- Embedded stores are appropriate for development and single-node evaluation; production deployments should use Qdrant or an equivalent distributed backend.
- When choosing a graph backend, validate both driver availability and licence compatibility before deployment, especially in Apache-licensed distributions.

## 6. Summary

MemMachine's storage layer cleanly separates vector similarity search, graph-based episodic traversal, and raw episode persistence behind pluggable interfaces. The current shipping backends cover local embedded use (SQLite, sqlite-vec, hnswlib, usearch) and production scale-out (Qdrant, Neo4j). Known concurrency issues in `SQLiteVectorStore` (#1468) and ongoing work to broaden backend choice (#1324, #1470) indicate an active roadmap focused on portability and licensing flexibility.

---

<a id='page-developer'></a>

## SDKs, REST API, MCP, and Framework Integrations

### Related Pages

Related topics: [MemMachine Overview & System Architecture](#page-overview), [Memory Architecture: Episodic, Profile/Semantic, and Working Memory](#page-memory)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/client/src/memmachine_client/client.py](https://github.com/MemMachine/MemMachine/blob/main/packages/client/src/memmachine_client/client.py)
- [packages/client/src/memmachine_client/project.py](https://github.com/MemMachine/MemMachine/blob/main/packages/client/src/memmachine_client/project.py)
- [packages/client/src/memmachine_client/memory.py](https://github.com/MemMachine/MemMachine/blob/main/packages/client/src/memmachine_client/memory.py)
- [packages/client/src/memmachine_client/langgraph.py](https://github.com/MemMachine/MemMachine/blob/main/packages/client/src/memmachine_client/langgraph.py)
- [packages/client/src/memmachine_client/cli.py](https://github.com/MemMachine/MemMachine/blob/main/packages/client/src/memmachine_client/cli.py)
- [packages/ts-client/src/client/memmachine-client.ts](https://github.com/MemMachine/MemMachine/blob/main/packages/ts-client/src/client/memmachine-client.ts)
</details>

# SDKs, REST API, MCP, and Framework Integrations

## Overview

MemMachine exposes its long-term memory capabilities through a layered integration surface: a REST/HTTP API at the server core, language-specific SDKs that wrap that API, and framework adapters that plug memory into agent runtimes. The Python SDK (`memmachine-client`) and the TypeScript SDK (`@memmachine/ts-client`) both follow the same conceptual model — a top-level `Client` that authenticates against an org/project, with `Project` and `Memory` resources underneath it. Source: [packages/client/src/memmachine_client/client.py:1-1](), [packages/ts-client/src/client/memmachine-client.ts:1-1]().

The community roadmap (#148) emphasizes that "developers today expect SDKs and React bindings that are intuitive, stable, and ready to use," which drives the priority of the SDK layer over hand-rolled HTTP calls. Recent releases (v0.3.7–v0.3.9) repeatedly regenerate the OpenAPI spec and prefer the released pip install path, signaling that the REST contract is the canonical source of truth and the SDKs mirror it.

## Python SDK (`memmachine-client`)

### Client and Project hierarchy

The top-level `Client` encapsulates connection, authentication, and project enumeration. It returns `Project` handles that scope all subsequent memory operations to a specific group/agent/producer tuple. Source: [packages/client/src/memmachine_client/client.py:1-1](), [packages/client/src/memmachine_client/project.py:1-1]().

`Project` is the operational unit: every memory read/write is bound to a project, and the project object exposes typed methods to obtain `Memory` resources for episodic or semantic memory types. This mirrors the server-side concept where each project has its own configuration file.

### Memory resource and operations

The `Memory` class (`memory.py`) is where the SDK diverges into episodic vs. semantic sub-resources. Both support `add`, `search`, and `delete` style operations, plus batch ingestion helpers. Known client-level bugs are tracked here:

- Bug #690: `MemMachineClient.search` returns episodic results but the `semantic_memory` field is always empty — a client-side serialization/parsing issue rather than a server one. Source: [packages/client/src/memmachine_client/memory.py:1-1]().
- Bug #640: Duplicate ingestion when the same message is sent repeatedly — duplication is server-side (citation table), but the Python SDK's batch helpers make it easy to trigger inadvertently.

### CLI

`memmachine-client` ships a `cli.py` entry point that lets users authenticate, list projects, and dump memory from the terminal. It is the same surface used in CI smoke tests and is the recommended path for quick verification before writing integration code. Source: [packages/client/src/memmachine_client/cli.py:1-1]().

## TypeScript SDK (`@memmachine/ts-client`)

The TypeScript client lives under `packages/ts-client` and exposes a `MemMachineClient` class with the same `Client → Project → Memory` hierarchy as the Python SDK. Source: [packages/ts-client/src/client/memmachine-client.ts:1-1]().

Notable behaviors documented in the release notes:

- v0.3.7 introduced an HTTPS-proxy fix (PR #1369) that auto-selects the appropriate `fetch` adapter when running behind corporate proxies — previously, undici-based fetch would fail in those environments.
- The TS client is the foundation for the proposed React bindings called out in issue #148 ("Frontend SDK Roadmap").

## Framework Integrations

### LangGraph

`memmachine-client/langgraph.py` provides a LangGraph-compatible memory adapter. It implements the LangGraph `BaseMemory` interface so a `CompiledStateGraph` can use MemMachine as a long-term store without bespoke serialization. The adapter typically wraps a `Project` and exposes `add` / `search` hooks tied to graph node transitions. Source: [packages/client/src/memmachine_client/langgraph.py:1-1]().

### Strands Agents

Added in v0.3.7 (PR #1330), the `strands-memmachine` integration wraps MemMachine as a Strands tool. This is a third-party-package integration: the core SDK does not depend on `strands-agents`, but the integration re-exports the same `Client`/`Project` types so existing usage patterns translate directly.

### MCP (Model Context Protocol)

The community context references MCP as part of the integration surface; in MemMachine, MCP compatibility is delivered via the framework adapters rather than a dedicated module, so any MCP-compliant runtime can consume the same `Memory` resource surface.

## REST API as the Canonical Contract

All SDKs are generated from (or kept in lockstep with) the server's OpenAPI specification. The repo regenerates `openapi.json` on every release (see v0.3.3, v0.3.6, v0.3.8, v0.3.9 release notes). Endpoints cluster under two prefixes:

| Prefix | Purpose | Typical methods |
|---|---|---|
| `/v1/projects/{project_id}/memory/episodic` | Episode append / search / delete | POST, GET, DELETE |
| `/v1/projects/{project_id}/memory/semantic` | Feature upsert / search / delete | POST, GET, DELETE |
| `/v1/projects` | Project CRUD | POST, GET, DELETE |

The SDKs map these 1:1 to Python methods and TS methods; any field not surfaced by the SDK is still reachable via raw HTTP, which is why the CLI doubles as a debugging tool.

## Choosing an Integration Path

- **Quick prototyping / scripts**: CLI or direct REST calls.
- **Python agents**: `memmachine-client` `Client` + `Memory`.
- **LangGraph / Strands**: use the framework adapter so memory hooks align with the agent lifecycle.
- **Browser / Node / React**: `ts-client`, optionally behind the planned React bindings from issue #148.
- **Other MCP runtimes**: instantiate the `Client` over HTTP, since the resource model is identical across surfaces.

In all cases, a project must exist on the server before any memory call will succeed — the SDK will surface a 404/403 if a `Project` handle is used against an unknown or unauthorized project.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: MemMachine/MemMachine

Summary: Found 12 structured pitfall item(s), including 3 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/MemMachine/MemMachine/issues/1324

## 2. Configuration risk - Configuration risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/MemMachine/MemMachine/issues/690

## 3. Configuration risk - Configuration risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/MemMachine/MemMachine/issues/640

## 4. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/MemMachine/MemMachine/issues/1468

## 5. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/MemMachine/MemMachine

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/MemMachine/MemMachine

## 7. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/MemMachine/MemMachine

## 8. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/MemMachine/MemMachine

## 9. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/MemMachine/MemMachine/issues/1270

## 10. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/MemMachine/MemMachine/issues/1470

## 11. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/MemMachine/MemMachine

## 12. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/MemMachine/MemMachine

<!-- canonical_name: MemMachine/MemMachine; human_manual_source: deepwiki_human_wiki -->