Memori - Moses Yebei

Abstract

Memori is agent-native memory infrastructure. A LLM-agnostic layer that turns agent execution and conversation into structured, persistent state for production systems.

The Problem

LLM agents have no persistent state. Every conversation starts from zero, so users re-explain preferences, agents re-discover context, and production systems can't audit what an agent actually knew. Memori turns agent execution and conversation into structured, queryable memory that survives across sessions.

What This Does

Memori is an agent-native memory layer that sits between your LLM and your datastore. It intercepts conversations and executions, extracts structured facts, and recalls them on demand. The repo implements this as a Rust core (core/src/lib.rs) with Python and TypeScript bindings, plus higher-level SDKs in memori/ (Python) and memori-ts/ (TypeScript).

The system is LLM-agnostic, datastore-agnostic, and framework-agnostic. It plugs into existing infrastructure — the README shows registering an OpenAI client and having memory persisted automatically. A managed cloud version exists at memorilabs.ai, with self-hosted options.

How It Is Wired

Execution starts in the Rust core. The entry points are core/src/runtime/worker.rs — start, submit, flush, shutdown — and core/bindings/python/src/lib.rs — execute. The Python binding calls back into the runtime via call_json_callback, fetch_embeddings, fetch_facts_by_ids, and write_batch. The Node bridge (core/bindings/node/src/bridge.rs) mirrors this pattern with PendingEmbeddingsMap, PendingFactsMap, and PendingWritesMap.

The core flow: execute → call_json_callback → model inference → write_batch → datastore. That's three hops from entry to persistence. The shutdown function is the widest blast radius — called from 9 places — so changing its behavior ripples through the entire runtime. The import graph shows a hub: memori/__init__.py has 62 modules depending on it, making it a high-churn, high-risk file.

The module graph also shows 23 modules inside circular dependencies, including memori/__init__.py and memori/llm/_base.py. Breaking those cycles requires extracting shared types or deferring imports — a non-trivial refactor.

How To Use It

Setup: Install the Python SDK (pip install memori) or TypeScript SDK (npm install @memorilabs/memori). For self-hosting, build the core with cargo build from core/.

Configuration: Set MEMORI_API_KEY and your LLM API key (e.g., OPENAI_API_KEY) in your environment. The .env.example file lists available options.

Running it: The README quickstart shows registering an OpenAI client and having memory persist automatically:

from memori import Memori
from openai import OpenAI

client = OpenAI()
mem = Memori().llm.register(client)
mem.attribution(entity_id="user_123", process_id="support_agent")

Real-World Use

A customer support agent that remembers user preferences across sessions. Register the LLM client, attribute the conversation to a user ID, and the system extracts and recalls facts like "favorite color is blue" without explicit memory management. Retrieval functions like search_facts and run_retrieval are called from 6 and 4 places respectively, indicating a well-used recall path.

Code Health & Issues

Static analysis found 136 findings (47 high, 89 medium) across 6 kinds. The most significant:

High - Import cycle members (15): memori/__init__.py, memori/llm/_base.py, memori-ts/src/core/config.ts participate in circular dependencies.
High - Deep nesting (18): memori/llm/_base.py reaches indentation depth 11; control flow is hard to follow.
High - Hub modules (7): memori/__init__.py has 62 dependents; changes here are high-blast-radius.
Medium - Broad exception handling (16): memori/__init__.py swallows errors indiscriminately.
Medium - Oversized file: memori/storage/drivers/mysql/_driver.py at 728 lines.

SDLC observations from the structure: CI exists via GitHub Actions, tests are present (189 test files), and a license is committed. The health audit flags two high-severity items: unpinned GitHub Actions (tags can be moved) and a missing lockfile for benchmarks/pyproject.toml.

The Bottom Line

Memori is a serious attempt at solving agent memory, with a clean Rust core and solid SDK coverage. The main risks are the circular imports and hub modules that make refactoring expensive. Worth evaluating if you need persistent agent state and can tolerate the maintenance cost of a polyglot codebase.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

628 files

Python280
TypeScript107
Rust39
Markdown28
YAML19
TOML18

ReactDockerTransformersLangChainVector store

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["tests 135 modules"] g1["memori 114 modules"] g2["memori-ts 75 modules"] g3["integrations 40 modules"] g4["examples 11 modules"] g5["(root) 2 modules"] g0 -->|196| g1 g4 -->|11| g1 g5 -->|2| g1 g3 -->|1| g1

Module dependencies

The 10 most depended-upon modules of 378, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_memori___init__["__init__"] n1_memori__config["_config"] n2_tests_database_core["core"] n3_memori_storage__registry["_registry"] n4_memori__exceptions["_exceptions"] n5_memori_llm__base["_base"] n6_memori_ts_src_core_config["config"] n7_memori_llm__utils["_utils"] n8_memori_ts_src_core_network["network"] n9_memori_ts_src_storage_base["base"] n0_memori___init__ --> n1_memori__config n0_memori___init__ --> n4_memori__exceptions n5_memori_llm__base --> n1_memori__config n5_memori_llm__base --> n7_memori_llm__utils n5_memori_llm__base --> n0_memori___init__ n3_memori_storage__registry --> n4_memori__exceptions n8_memori_ts_src_core_network --> n6_memori_ts_src_core_config classDef cyc stroke:#ef4444,stroke-width:2px; class n0_memori___init__,n5_memori_llm__base,n6_memori_ts_src_core_config cyc;

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium7

low1

Pin third-party GitHub Actions to a commit SHAhigh6 occurrences

.github/workflows

dtolnay/rust-toolchain@stable, Swatinem/rust-cache@v2, pypa/cibuildwheel@v3.4.0, android-actions/setup-android@v3

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Commit a lockfile beside the manifesthigh

benchmarks/pyproject.toml

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/core-ci.yml

1 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

10 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

Dockerfile

python:3.12-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Split the oversized notebook cell into stepsmedium

benchmarks/02_run_benchmark.ipynb

largest cell 4654 characters of 25348 (2 notebooks sampled)

A failure anywhere in a 22,000-character cell means rerunning the whole pipeline from load to model, so nothing can be debugged in isolation.

Fix: Break at the load, clean, feature, model and evaluate boundaries.

Set persist-credentials: false on checkoutmedium

.github/workflows/core-ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/core-ci.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.