Memoria - Moses Yebei

The Problem

AI agents that rely on long‑term context often lose consistency: memories drift, contradictions appear, and rollback is manual. Without a versioned store, developers must rebuild prompts or re‑ingest data, leading to hallucinations and wasted compute.

What This Does

Memoria implements a Git‑style, copy‑on‑write memory layer built on MatrixOne’s vector‑enabled storage. Core crates provide the API (memoria/crates/memoria‑api/src/lib.rs), the CLI (memoria/crates/memoria‑cli/src/main.rs), the embedding service (memoria/crates/memoria‑embedding/src/lib.rs), and the MCP‑compatible server (memoria/crates/memoria‑mcp/src/server.rs). Plugins (e.g., plugins/openclaw/) add agent‑specific adapters. The system snapshots, branches, and merges memory graphs while preserving semantic search indexes.

How It Is Wired

Execution starts at memoria/crates/memoria‑cli/src/main.rs (the main function, 2 593 lines, reaches 358 functions). main parses CLI flags, builds a MemoriaCli instance, and ultimately calls cmd_init_interactive, which invokes the LLM model via the string "openai" (model inference path).

The HTTP server entry point is memoria/crates/memoria‑mcp/src/server.rs:dispatch (reaches 189 functions). dispatch calls call, which constructs a request to self.client.post(self.url("/v1/memories/correct")) – a network outbound call – and may also trigger a model inference (service.llm.is_none).

Benchmark runs use memoria/crates/memoria‑cli/src/benchmark_executor.rs:execute (235 functions).

Across the codebase the most widely referenced symbols are setup (called from 164 places), uid (149), header (134) and post (133). These functions sit in memoria/crates/memoria‑api/src/lib.rs and memoria/crates/memoria‑api/src/routes/*.rs; changes to them have the largest blast radius.

External effects are concentrated in a handful of paths:

Model inference – main → cmd_init_interactive and dispatch → call.
Network I/O – run → preflight (client health check) and dispatch → call.
Database I/O – setup → new_sql_with_llm.
Filesystem – main writes/reads files for configuration and snapshots.

No circular module dependencies were detected, and the internal call graph contains 3 307 resolved edges, confirming a relatively flat dependency structure.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/Memoria
cd Memoria

# Build all Rust crates (requires Rust toolchain)
make -C memoria          # invokes `cargo build --workspace`

# (Optional) Run the service via Docker
docker compose up -d     # uses docker-compose.yml and Dockerfile

# Set runtime configuration – copy the example env file
cp memoria/.env.example .env   # edit .env as needed (e.g., DB_URL, LLM_ENDPOINT)

# Start the CLI (default starts a local server)
cargo run -p memoria-cli -- serve   # entry point: memoria/crates/memoria-cli/src/main.rs

# Example: create a snapshot via the HTTP API
curl -X POST http://localhost:8080/v1/memories/snapshot \
     -H "Authorization: Bearer <token>"

The repository ships a Makefile at the root and inside memoria/ that expose the typical targets (build, test, docker-build). No additional package managers are required beyond Cargo and Docker.

Real‑World Use

A customer integrating a code‑assistant bot adds plugins/openclaw/ to expose the agent’s memory through the OpenClaw protocol. When the bot writes a new fact, the plugin calls memoria/crates/memoria‑service/src/service.rs:round4, which stores the fact, triggers a governance check, and writes a snapshot. If the fact later contradicts existing knowledge, the governance hook (memoria/crates/memoria-service/src/plugin/governance_hook.rs) automatically quarantines it, preserving consistency without manual intervention.

Code Health & Issues

Static analysis findings (61 total)

HIGH – Oversized files (plugins/openclaw/openclaw/config.ts, plugins/openclaw/openclaw/client.ts, memoria/crates/memoria-api/tests/api_db_verify.rs) – >600 lines each, hard to reason about.
HIGH – Deep nesting (memoria/crates/memoria-api/src/lib.rs, .../routes/sessions.rs, memoria/crates/memoria-cli/src/bin/loadtest.rs) – indentation depth 8.
HIGH – Duplicated code blocks across multiple modules (≈350 repeats).
MEDIUM – High branching density in several plugin scripts.

Code‑health audit (8 findings)

Severity	Issue	Location
High	Pin third‑party GitHub Actions to a commit SHA	`.github/workflows/*`
Medium	Declare least‑privilege `GITHUB_TOKEN` permissions	`.github/workflows/release-docker.yml`
Medium	Enable Dependabot / Renovate	repo root (no config)
Medium	Pin Docker base images by digest	`memoria/Dockerfile`
Medium	Add a dependency‑vulnerability scan step	`.github/workflows/*`
Medium	Set `persist-credentials: false` on checkout	`.github/workflows/release-npm.yml`
Low	Add `timeout-minutes` to workflow jobs	`.github/workflows/release-docker.yml`
Low	Add convention files (`.editorconfig`, `.gitattributes`, formatter config)	repo root

All findings are deterministic; the listed fixes are the recommended actions.

The Bottom Line

Memoria delivers a production‑ready, versioned memory store for AI agents, with a well‑structured Rust codebase and Docker support. The core architecture is clear, but several large, deeply nested files and duplicated snippets increase maintenance overhead, and the CI pipeline needs tightening (action pinning, permission scoping, dependency scans). Teams comfortable with Rust and containerised deployment will find it immediately usable; others should budget time for refactoring the high‑cognitive‑load modules and hardening the CI workflow.

What the analyser found

Deployment readiness

7/7

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

Composition

329 files

Rust182
Markdown55
YAML17
TOML17
JSON16
TypeScript12

ReactDocker

Module dependencies

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

graph LR n0_ins_openclaw_openclaw_config["config"] n1_ins_openclaw_openclaw_client["client"] n2_penclaw_openclaw_http_client["http-client"] n3_w_openclaw___tests___helpers["helpers"] n4_ins_openclaw_openclaw_format["format"] n5_enclaw___tests___client_test["client.test"] n6_gins_openclaw_openclaw_index["index"] n7_enclaw___tests___format_test["format.test"] n8_w___tests___http_client_test["http-client.test"] n9_nclaw___tests___parsers_test["parsers.test"] n5_enclaw___tests___client_test --> n1_ins_openclaw_openclaw_client n5_enclaw___tests___client_test --> n2_penclaw_openclaw_http_client n5_enclaw___tests___client_test --> n3_w_openclaw___tests___helpers n7_enclaw___tests___format_test --> n4_ins_openclaw_openclaw_format n7_enclaw___tests___format_test --> n1_ins_openclaw_openclaw_client n3_w_openclaw___tests___helpers --> n0_ins_openclaw_openclaw_config n8_w___tests___http_client_test --> n2_penclaw_openclaw_http_client n8_w___tests___http_client_test --> n3_w_openclaw___tests___helpers n9_nclaw___tests___parsers_test --> n2_penclaw_openclaw_http_client n9_nclaw___tests___parsers_test --> n3_w_openclaw___tests___helpers n1_ins_openclaw_openclaw_client --> n0_ins_openclaw_openclaw_config n1_ins_openclaw_openclaw_client --> n2_penclaw_openclaw_http_client n4_ins_openclaw_openclaw_format --> n1_ins_openclaw_openclaw_client n2_penclaw_openclaw_http_client --> n0_ins_openclaw_openclaw_config n6_gins_openclaw_openclaw_index --> n0_ins_openclaw_openclaw_config n6_gins_openclaw_openclaw_index --> n1_ins_openclaw_openclaw_client n6_gins_openclaw_openclaw_index --> n4_ins_openclaw_openclaw_format

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.

high1

medium5

low2

Pin third-party GitHub Actions to a commit SHAhigh9 occurrences

.github/workflows

docker/setup-qemu-action@v3, docker/setup-buildx-action@v3, docker/login-action@v3, docker/metadata-action@v5

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.

Declare least-privilege permissions for GITHUB_TOKENmedium2 occurrences

.github/workflows/release-docker.yml

2 workflow(s) declare no permissions, 2 of them reference secrets

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

11 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 digestmedium2 occurrences

memoria/Dockerfile

rust:${RUST_VERSION}-slim, debian:bookworm-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.

Set persist-credentials: false on checkoutmedium

.github/workflows/release-npm.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.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/release-docker.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.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

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.