# gibsonai/memori architecture

> Architecture diagram of the GitHub repository gibsonai/memori, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gibsonai/memori
- Repository: https://github.com/gibsonai/memori

## Overview

Memori is a persistent-memory SDK and agent integration suite. In the principal workflow, an application’s LLM interaction is captured and attributed, augmented into structured memories, and persisted; later requests retrieve relevant memories for recall or prompt injection. The Python and TypeScript packages expose parallel SDK surfaces, with the TypeScript native engine delegating storage operations through its storage manager. README capabilities also include explicit agent recall, OpenClaw and Hermes integrations, MCP access, and BYODB. Some integration wiring is documented rather than sampled, so those relationships are shown only at the documented boundary.

Main entry points: [`memori/agent.py`](https://github.com/gibsonai/memori/blob/main/memori/agent.py) (Python SDK), [`memori/memory/recall.py`](https://github.com/gibsonai/memori/blob/main/memori/memory/recall.py) (Recall and search), [`memori/llm/clients`](https://github.com/gibsonai/memori/tree/main/memori/llm/clients) (LLM adapters), [`memori/memory/augmentation/_manager.py`](https://github.com/gibsonai/memori/blob/main/memori/memory/augmentation/_manager.py) (Memory augmentation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sdk["SDK workflows"]
  node_py_sdk["Python SDK<br/>[agent.py]"]
  node_ts_sdk["TypeScript SDK<br/>[memori.ts]"]
  node_llm_hooks["LLM adapters"]
end

subgraph group_memory["Memory processing"]
  node_capture["Conversation capture<br/>[_manager.py]"]
  node_augmentation["Memory augmentation<br/>[_manager.py]"]
  node_recall["Recall and search<br/>[recall.py]"]
  node_embedding["Embeddings"]
  node_search["Fact ranking<br/>[_api.py]"]
end

subgraph group_persistence["Persistence"]
  node_py_storage["Python storage<br/>[_manager.py]"]
  node_ts_storage["TS storage manager<br/>[manager.ts]"]
  node_rust_storage["Rust storage manager<br/>[manager.rs]"]
end

subgraph group_integrations["Agent integrations"]
  node_openclaw["OpenClaw plugin<br/>[index.ts]"]
  node_hermes["Hermes provider<br/>[tools.py]"]
  node_claude["Claude Code MCP<br/>[index.ts]"]
end

subgraph group_platform["Native platform"]
  node_native_core["Rust memory engine<br/>[lib.rs]"]
  node_ts_engine["TS engine bridge<br/>[engine.ts]"]
  node_node_binding["Node binding<br/>[engine.rs]"]
  node_py_binding["Python binding<br/>[lib.rs]"]
end

node_app(("Agent application"))
node_llm(("LLM provider"))
node_databases[("Configured datastore")]
node_cloud["Memori Cloud API"]
node_agent_tools(("Agent clients"))

node_app -->|"uses"| node_py_sdk
node_app -->|"uses"| node_ts_sdk
node_llm_hooks -->|"calls"| node_llm
node_app -->|"registers"| node_llm_hooks
node_llm_hooks -->|"captures turns"| node_capture
node_capture -->|"schedules"| node_augmentation
node_augmentation -->|"embeds facts"| node_embedding
node_augmentation -->|"enqueues writes"| node_py_storage
node_py_sdk -->|"manages memory"| node_capture
node_py_sdk -->|"requests recall"| node_recall
node_recall -->|"embeds query"| node_embedding
node_recall -->|"ranks candidates"| node_search
node_recall -->|"fetches facts"| node_py_storage
node_ts_sdk -->|"invokes"| node_ts_engine
node_ts_engine -->|"calls native"| node_node_binding
node_node_binding -->|"delegates"| node_native_core
node_native_core -->|"retrieves and writes"| node_rust_storage
node_ts_engine -->|"services storage calls"| node_ts_storage
node_ts_storage -->|"reads and writes"| node_databases
node_py_storage -->|"reads and writes"| node_databases
node_rust_storage -->|"uses host bridge"| node_databases
node_py_sdk -.->|"sends memory"| node_cloud
node_openclaw -.->|"uses SDK"| node_ts_sdk
node_hermes -.->|"offers recall tools"| node_agent_tools
node_agent_tools -.->|"requests recall"| node_hermes
node_claude -.->|"connects via MCP"| node_agent_tools

click node_py_sdk "https://github.com/gibsonai/memori/blob/main/memori/agent.py"
click node_ts_sdk "https://github.com/gibsonai/memori/blob/main/memori-ts/src/memori.ts"
click node_llm_hooks "https://github.com/gibsonai/memori/tree/main/memori/llm/clients"
click node_capture "https://github.com/gibsonai/memori/blob/main/memori/memory/_manager.py"
click node_augmentation "https://github.com/gibsonai/memori/blob/main/memori/memory/augmentation/_manager.py"
click node_recall "https://github.com/gibsonai/memori/blob/main/memori/memory/recall.py"
click node_embedding "https://github.com/gibsonai/memori/tree/main/memori/embeddings"
click node_search "https://github.com/gibsonai/memori/blob/main/memori/search/_api.py"
click node_native_core "https://github.com/gibsonai/memori/blob/main/core/src/lib.rs"
click node_ts_engine "https://github.com/gibsonai/memori/blob/main/memori-ts/src/core/engine.ts"
click node_node_binding "https://github.com/gibsonai/memori/blob/main/core/bindings/node/src/engine.rs"
click node_py_binding "https://github.com/gibsonai/memori/blob/main/core/bindings/python/src/lib.rs"
click node_py_storage "https://github.com/gibsonai/memori/blob/main/memori/storage/_manager.py"
click node_ts_storage "https://github.com/gibsonai/memori/blob/main/memori-ts/src/storage/manager.ts"
click node_rust_storage "https://github.com/gibsonai/memori/blob/main/core/src/storage/manager.rs"
click node_openclaw "https://github.com/gibsonai/memori/blob/main/integrations/openclaw/src/index.ts"
click node_hermes "https://github.com/gibsonai/memori/blob/main/integrations/hermes/src/memori_hermes/tools.py"
click node_claude "https://github.com/gibsonai/memori/blob/main/integrations/claude-code/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_py_sdk,node_ts_sdk,node_llm_hooks,node_agent_tools toneBlue
class node_capture,node_augmentation,node_recall,node_embedding,node_search,node_databases toneAmber
class node_py_storage,node_ts_storage,node_rust_storage,node_cloud toneMint
class node_openclaw,node_hermes,node_claude toneRose
class node_native_core,node_ts_engine,node_node_binding,node_py_binding,node_app,node_llm toneIndigo
```

## Components

### SDK workflows

- [Python SDK](https://github.com/gibsonai/memori/blob/main/memori/agent.py): `memori/agent.py`
- [TypeScript SDK](https://github.com/gibsonai/memori/blob/main/memori-ts/src/memori.ts): `memori-ts/src/memori.ts`
- [LLM adapters](https://github.com/gibsonai/memori/tree/main/memori/llm/clients): `memori/llm/clients`

### Memory processing

- [Conversation capture](https://github.com/gibsonai/memori/blob/main/memori/memory/_manager.py): `memori/memory/_manager.py`
- [Memory augmentation](https://github.com/gibsonai/memori/blob/main/memori/memory/augmentation/_manager.py): `memori/memory/augmentation/_manager.py`
- [Recall and search](https://github.com/gibsonai/memori/blob/main/memori/memory/recall.py): `memori/memory/recall.py`
- [Embeddings](https://github.com/gibsonai/memori/tree/main/memori/embeddings): `memori/embeddings`
- [Fact ranking](https://github.com/gibsonai/memori/blob/main/memori/search/_api.py): `memori/search/_api.py`

### Persistence

- [Python storage](https://github.com/gibsonai/memori/blob/main/memori/storage/_manager.py): `memori/storage/_manager.py`
- [TS storage manager](https://github.com/gibsonai/memori/blob/main/memori-ts/src/storage/manager.ts): `memori-ts/src/storage/manager.ts`
- [Rust storage manager](https://github.com/gibsonai/memori/blob/main/core/src/storage/manager.rs): `core/src/storage/manager.rs`

### Agent integrations

- [OpenClaw plugin](https://github.com/gibsonai/memori/blob/main/integrations/openclaw/src/index.ts): `integrations/openclaw/src/index.ts`
- [Hermes provider](https://github.com/gibsonai/memori/blob/main/integrations/hermes/src/memori_hermes/tools.py): `integrations/hermes/src/memori_hermes/tools.py`
- [Claude Code MCP](https://github.com/gibsonai/memori/blob/main/integrations/claude-code/index.ts): `integrations/claude-code/index.ts`

### Native platform

- [Rust memory engine](https://github.com/gibsonai/memori/blob/main/core/src/lib.rs): `core/src/lib.rs`
- [TS engine bridge](https://github.com/gibsonai/memori/blob/main/memori-ts/src/core/engine.ts): `memori-ts/src/core/engine.ts`
- [Node binding](https://github.com/gibsonai/memori/blob/main/core/bindings/node/src/engine.rs): `core/bindings/node/src/engine.rs`
- [Python binding](https://github.com/gibsonai/memori/blob/main/core/bindings/python/src/lib.rs): `core/bindings/python/src/lib.rs`

### Other components

- **Agent application**
- **LLM provider**
- **Configured datastore**
- **Memori Cloud API**
- **Agent clients**

## Connections

- Agent application → Python SDK: uses
- Agent application → TypeScript SDK: uses
- LLM adapters → LLM provider: calls
- Agent application → LLM adapters: registers
- LLM adapters → Conversation capture: captures turns
- Conversation capture → Memory augmentation: schedules
- Memory augmentation → Embeddings: embeds facts
- Memory augmentation → Python storage: enqueues writes
- Python SDK → Conversation capture: manages memory
- Python SDK → Recall and search: requests recall
- Recall and search → Embeddings: embeds query
- Recall and search → Fact ranking: ranks candidates
- Recall and search → Python storage: fetches facts
- TypeScript SDK → TS engine bridge: invokes
- TS engine bridge → Node binding: calls native
- Node binding → Rust memory engine: delegates
- Rust memory engine → Rust storage manager: retrieves and writes
- TS engine bridge → TS storage manager: services storage calls
- TS storage manager → Configured datastore: reads and writes
- Python storage → Configured datastore: reads and writes
- Rust storage manager → Configured datastore: uses host bridge
- Python SDK → Memori Cloud API: sends memory
- OpenClaw plugin → TypeScript SDK: uses SDK
- Hermes provider → Agent clients: offers recall tools
- Agent clients → Hermes provider: requests recall
- Claude Code MCP → Agent clients: connects via MCP