MemoryOS - Moses Yebei

The Problem

LLM agents forget. A chatbot that cannot recall what a user said last week produces repetitive, context-blind answers. MemoryOS addresses this with a hierarchical memory system inspired by OS memory management: short-term, mid-term, and long-term storage with explicit update, retrieval, and generation phases. It reports a 49.11% F1 improvement on the LoCoMo benchmark.

What This Does

MemoryOS is five self-contained Python projects, not a single codebase. memoryos-pypi is the core library: short_term.py, mid_term.py, and long_term.py implement the three-tier memory hierarchy, coordinated by memoryos.py. memoryos-chromadb is a variant backed by ChromaDB, with storage_provider.py handling vector collections. memoryos-mcp exposes the same functionality as an MCP server for agent tool integration. memoryos-playground is a Flask demo (memdemo/app.py) with a web UI. eval/ contains the LoCoMo benchmark harness.

All variants share the same architecture: utils.py provides chat_completion, get_embedding, and get_timestamp; memory classes handle promotion between tiers; updater.py and retriever.py manage knowledge extraction and recall.

How It Is Wired

Execution starts at three Flask routes in memoryos-playground/memdemo/app.py: chat (reaches 72 functions), import_conversations (58), and trigger_analysis (35). These route into add_memory, which calls _trigger_profile_and_knowledge_update_if_needed and makes an outbound network call via session.get within two hops.

The highest fan-in functions are get_timestamp (24 call sites), chat_completion (14), and get_embedding (11). eval/utils.py — despite its name — is the true hub: 15 functions called from 17 other files, and it performs model inference. The storage_provider.py file owns vector storage; mid_term.py owns heat/recency scoring; long_term.py owns user profiles and assistant knowledge.

The module graph shows import cycles across all four variants (33 modules in circular dependencies). The most unstable modules are the top-level memoryos.py files (instability ~0.88), meaning changing them risks breaking everything that imports them. utils.py files are stable (0.14) but sit inside cycles, so refactoring them requires coordinated changes across the variant.

How To Use It

git clone https://github.com/moses-y/MemoryOS
cd MemoryOS/memoryos-pypi
pip install -r requirements.txt

Run the playground:

cd ../memoryos-playground/memdemo
./start_demo.sh

Configuration lives in memoryos-mcp/config.json and mcp.json. The playground requires an OpenAI-compatible API key. The README documents Docker deployment; the root Dockerfile uses python:3.10-slim.

Real-World Use

An agent that remembers a user's stated preferences across sessions. Call add_memory with each conversation turn; MemoryOS promotes important facts to long-term storage and retrieves them when the user returns. The MCP server (memoryos-mcp/server_new.py) exposes these operations as tools any MCP-compatible agent can call.

Code Health & Issues

Static analysis found 69 findings (47 high, 22 medium): 33 import-cycle memberships, 20 deeply nested blocks (max depth 8 in mid_term.py), broad exception handling in storage_provider.py and eval/long_term_memory.py, and 1,610 duplicated 6-line blocks across 36 files. The code health audit flags three high issues: no CI workflow, no Docker build gate, and app.run(debug=True) in memdemo/app.py — a production risk. Medium issues: no dependency update bot, unpinned base image, and a 0.038 test-to-source ratio (2 test files, 52 source files).

The Bottom Line

The memory architecture is sound and the benchmark results are credible. The duplication across five variants will make maintenance expensive, and the missing CI is risky for a research codebase. Use it if you need a proven hierarchical memory layer and can tolerate the upkeep.

What the analyser found

Deployment readiness

5/7

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

Composition

73 files

Python52
JSON4
Markdown2
HTML2
Shell1

FlaskDockerVector store

Module dependencies

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

graph LR n0_memoryos_chromadb_utils["utils"] n1_memoryos_mcp_memoryos_utils["utils"] n2_memoryos_playground_utils["utils"] n3_memoryos_pypi_utils["utils"] n4_os_chromadb_storage_provider["storage_provider"] n5_memoryos_chromadb_long_term["long_term"] n6_memoryos_chromadb_mid_term["mid_term"] n7_memoryos_chromadb_short_term["short_term"] n8_oryos_mcp_memoryos_long_term["long_term"] n9_moryos_mcp_memoryos_mid_term["mid_term"] n5_memoryos_chromadb_long_term --> n0_memoryos_chromadb_utils n5_memoryos_chromadb_long_term --> n4_os_chromadb_storage_provider n6_memoryos_chromadb_mid_term --> n0_memoryos_chromadb_utils n6_memoryos_chromadb_mid_term --> n4_os_chromadb_storage_provider n7_memoryos_chromadb_short_term --> n4_os_chromadb_storage_provider n4_os_chromadb_storage_provider --> n0_memoryos_chromadb_utils n8_oryos_mcp_memoryos_long_term --> n1_memoryos_mcp_memoryos_utils n9_moryos_mcp_memoryos_mid_term --> n1_memoryos_mcp_memoryos_utils classDef cyc stroke:#ef4444,stroke-width:2px; class n0_memoryos_chromadb_utils,n1_memoryos_mcp_memoryos_utils,n2_memoryos_playground_utils,n3_memoryos_pypi_utils,n4_os_chromadb_storage_provider,n5_memoryos_chromadb_long_term,n6_memoryos_chromadb_mid_term,n7_memoryos_chromadb_short_term,n8_oryos_mcp_memoryos_long_term,n9_moryos_mcp_memoryos_mid_term cyc;

Findings

MediumNo CI/CD pipeline detected - no automated build/test gate .github/ or CI config
LowDependencies declared without a lockfile - non-reproducible builds memoryos-chromadb/requirements.txt

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.

high3

medium3

Add a workflow that builds and tests this repositoryhigh

52 source files, no CI configuration

Every change merges with nobody having run the build once, which across this estate is 499 repositories.

Fix: Add a workflow running the project build and test command on push and pull_request.

Add a build gate for the deployable artifacts herehigh

Dockerfile

deployment artifacts with no workflow

Something in the repo is meant to reach a server and no automated step has ever validated it, which is the state of 125 repositories here.

Fix: Add a workflow that at least builds the image and validates the manifests.

Turn off debug mode and drive it from the environmenthigh

memoryos-playground/memdemo/app.py

app.run(debug=True)

Django and Flask debug pages render local variables, settings and the full traceback to whoever triggered the error, so one unhandled exception publishes the database password to a stranger, and Werkzeug's debugger additionally offers a remote shell.

Fix: Read it from the environment with a safe default: DEBUG = os.environ.get("DEBUG") == "1".

Enable Dependabot or Renovatemedium

6 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.10-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.

Expand the test suite; it cannot cover this codebasemedium2 occurrences

2 test files against 52 source files (ratio 0.038)

A reviewer reads "has tests" and assumes a safety net that covers two files out of eighty-five, which is how untested paths ship behind a green badge.

Fix: Add tests for the highest fan-in modules first.

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.