convez.ai
AgenteAutomaçãoAvançado
cremenescu

mem0ry4ai — Memória Persistente para Agentes de Código

cremenescu/mem0ry4ai

Memória durável, git-versionada, para agentes que precisam lembrar

Ver no GitHub
BomPluginScore · de 0 a 100

Sistema de memória local-first que persiste conhecimento entre sessões de agentes (Claude Code) usando markdown versionado por git e índice FTS5. Captura seletiva com gates de confiança, injeção automática e escopo por projeto reduzem em ~88% o contexto carregado mantendo relevância máxima.

Instalação

$npx convez-ai cremenescu/mem0ry4ai

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 3 meses
Versão
v0.20.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Agentes que precisam acumular gotchas e decisões entre sessões sem esquecer
  • Projetos monorepo onde cada sub-projeto tem contexto diferente
  • Redução de tokens injetos mantendo regras críticas sempre acessíveis

Veredito

Solução pragmática que resolve friç real: agentes esquecem entre sessões e ferramentas de memória convencionais ou falham ou inflam contexto. Abordagem markdown+git+FTS5 é resiliente, auditável e mede impacto real (88% redução tokens em uso real). Para quem constrói agentes Claude sérios.

README

A tradução para o português deste README ainda está na fila.

mem0ry4ai

Persistent, local-first memory for coding agents — built for Claude Code.

Landing page: cremenescu.ro/en/mem0ry4ai

Your agent forgets everything between sessions. mem0ry4ai fixes that: it captures durable knowledge (gotchas, decisions, facts, commands, preferences, todos, project status), stores it in plain markdown versioned by git, and injects the relevant slice automatically at the start of every session — scoped to the project you are working in.

Why another memory tool?

We surveyed the landscape first (claude-mem, basic-memory, mem0, Letta/MemGPT, Graphiti, agentmemory, the official MCP memory server). Recurring failure modes shaped this design:

Common failuremem0ry4ai answer
Model forgets to call save/recall toolsDeterministic hooks inject at SessionStart; the agent is instructed to write proactively
Vector DB fragility (Chroma/Qdrant = #1 source of real bug reports)Markdown + git is the source of truth; SQLite FTS5 index is derived and disposable
Memory rots (stale facts, contradictions)Supersede, never delete — old records keep history; git keeps everything
Auto-extraction noise (small LLMs are over-confident: ~1.0 confidence on everything — we measured)Trust-gated writes: the in-context agent writes directly; batch LLM extraction goes through a human review queue
Tools that vandalize CLAUDE.md / fight native memoryCoexists cleanly — own namespace, never touches your files
Nobody remembers "where was I?" on returning to a projectFirst-class todo and status types, pinned in injection and UI
Credentials accumulate in an unencrypted memory fileSecret redaction on every write path (8 patterns: API keys, Bearer/GitHub/OpenAI/Slack tokens, AWS keys, private keys, passwords) + mem.py audit for what is already stored
As memory grows, the injection grows — and the harness truncates it blindly, silently dropping rules the agent must followSelf-budgeted injection: priority: critical rules are always in (first, full body); the rest fills MEM_INJECT_BUDGET; every cut is announced with the command that retrieves it

Measured impact (author's real setup)

This is not a synthetic benchmark — it is the author's actual monorepo (30 sub-projects), before and after migrating a monolithic CLAUDE.md into mem0ry4ai (217 active memories):

Before (one big CLAUDE.md)After (slim CLAUDE.md + injection)
Fixed context loaded at every session start242,956 bytes (1,832 lines) ≈ ~61k tokensrepo root: 29,169 bytes ≈ ~7.3k tokens · sub-project: 19,044 bytes ≈ ~4.8k tokens
Reduction—88% (root) / 92% (sub-project)
Relevanceeverything, everywhere (FreeRDP gotchas while editing a weather app)scoped: global + the current project; status/todo first
SessionStart hook overhead—69 ms
Live-update poll (no changes)—~1–4 ms

At the author's measured pace (34 session starts/day) that is roughly 1.8M tokens/day of context that no longer gets loaded — while recall got better, because memories are scoped, ranked-searchable and pinned by relevance instead of buried in a 240KB file.

Honest caveats: tokens estimated at ~4 chars/token; with prompt caching the billed savings are smaller than the raw numbers; this is one user's setup, not a controlled study.

How it works

Claude Code session
  ├─ SessionStart hook ─► injects relevant memories (global + current project;
  │                       from a monorepo root: a capped index of ALL projects)
  ├─ [work] the agent proactively writes durable findings ─► mem.py add
  └─ SessionEnd/PreCompact hook ─► transcript pointer to staging/ + auto-commit of the
                                    store (end-of-session git checkpoint — no manual chore)

store/*.md   ◄── SOURCE OF TRUTH (markdown + git: audit, diff, rollback, supersede)
   ├─► store/.index.db   (FTS5, ranked search — derived, regenerable)
   ├─► web UI            (dashboard, per-project "where was I" page, review queue, live updates)
   └─► mem.py            (CLI: add/list/search/supersede/propose/reindex — stdlib only)

Quick start

Requirements: Python 3.9+, PHP 8+ (for the web UI), git. No other dependencies — no Docker, no vector database, no API keys.

Option A — Claude Code plugin (one command)

claude plugin marketplace add cremenescu/mem0ry4ai
claude plugin install mem0ry4ai@mem0ry4ai

Restart Claude Code — hooks (inject at start, capture + git checkpoint at end) register automatically and the web UI starts with your first session. In plugin installs your data lives in ~/.mem0ry4ai (its own git repo, created on first write), so plugin updates never touch your memories. The injected context header shows the exact mem.py path to use from inside a session.

Option B — git clone (data stays in your clone)

git clone https://github.com/cremenescu/mem0ry4ai.git
cd mem0ry4ai

# 1. CLI works immediately
./mem.py add --type gotcha --scope global \
  --summary "openrsync on macOS does not support --chown" \
  --body "Use --rsync-path=\"sudo rsync\" and chown separately over ssh."
./mem.py list
./mem.py search "rsync"                    # FTS5 ranked
./mem.py search "rsync" --since 2026-05-01 # ...only memories created since May
./mem.py audit                             # report secret-like patterns (read-only)

# 2. Web UI (standalone server, no Apache needed)
./server_web.sh                   # -> http://127.0.0.1:8841/

# 3. Claude Code integration (hooks: inject at start + capture at end)
python3 hooks/install.py --dry-run        # preview what would be written
python3 hooks/install.py --target user    # ~/.claude/settings.json (all projects)
# restart Claude Code (or /clear) to load the hooks

The SessionStart hook also auto-starts the web server, so the UI is always up while you work.

Teach your agent to write memories

Add an instruction like this to your CLAUDE.md (this is the behavioral half of the system — hooks handle recall, the agent handles capture):

When you discover something durable (a gotcha with a non-obvious cause, an architecture decision, an infrastructure fact, a reusable command, a user preference/correction, a change of project status), proactively save it without asking: echo "body" | <path>/mem.py add --type <T> --scope <global|project:slug> --summary "..." --source claude:live Check mem.py search first to avoid duplicates. Never save ephemeral tasks.

Memory types

TypeWhat it holds
gotchatrap + cause + fix ("X breaks because Y, do Z")
decisionarchitecture choice + the why
factstable infrastructure facts (hosts, paths, ports)
commanda command you would otherwise look up again
preferenceuser style/conventions/corrections
todowhat remains to be done (supersede when finished)
statuswhere the project stands / where you left off

todo + status are pinned first in injection and in the per-project web page — they answer "where was I?" when you return to a project after weeks.

Critical rules and the injection budget

A memory system has a failure mode nobody talks about: the more it remembers, the longer the injected context gets — until the harness starts truncating it, blindly. Claude Code persists oversized hook output to a file and shows the model only a small preview; whatever falls past the cut is invisible, and the model cannot follow a rule it cannot see. We hit this in production: a "never add Co-Authored-By to commits" preference fell past the cut and the agent violated it.

The fix is that the injection trims itself, deterministically, before the harness ever has to:

  • priority: critical — pin the rules that gate the agent's actions ("never X in commits", "never touch production", "always test on one device first"):
    ./mem.py pin <id>            # or: ./mem.py add ... --critical
    
    Critical rules are injected always, first, with their full body, regardless of budget.
  • MEM_INJECT_BUDGET (default 8000 bytes) — everything else fills the budget in relevance order (current project's status/todo first, then global knowledge, then recently-touched projects), and every cut is announced in the injection itself: (+12 omitted by budget — mem.py list --scope ...). Nothing disappears silently.
  • The dashboard health panel shows the real injection size vs the budget, and the "What Claude sees" page renders exactly what the agent gets.

Secret redaction

The store is plain markdown versioned by git — a credential that lands there is hard to remove retroactively (it survives in git history). So every write path redacts secrets by default, replacing values with [REDACTED:<label>]:

  • mem.py add / mem.py propose — the saved memory keeps what kind of secret was used ("the command used a Bearer token"), never the value.
  • consolidate.py — transcripts routinely contain .env reads, curl headers and passwords; they are redacted before the text even reaches the local LLM, and candidates are redacted again before queueing.
  • mem.py audit — read-only report of secret-like patterns already in the store (exit 1 if any found, handy in CI). It never modifies records — you decide what to clean up.

Patterns: generic API/secret/access keys, Bearer tokens, AWS keys, private key blocks, quoted passwords, GitHub/OpenAI/Slack tokens. Opt out per call with --no-redact, or globally with MEM_REDACT=0. Infrastructure facts you store on purpose (hosts, paths, ports, usernames) are not touched — only credential-shaped values are.

For secrets the agent should be able to use across sessions, store a pointer, not the value: keep the secret in your OS keychain / password manager, and save a fact telling the agent where it lives and a command that fetches it at use time.

Web UI

Bilingual (English default, Romanian via the EN/RO switch in the top bar).

Dashboard — system status, health checks, recent activity, grouped memories

Per-project "where was I?" page — status and todos pinned first:

Project page

The review queue — the over-confident junk candidate (conf 0.95 for "updated the changelog") is exactly why nothing auto-writes:

Review queue

"What Claude sees" — the exact SessionStart injection, with its cost:

What Claude sees

Git history — the memory timeline with per-commit diffs and commit-from-UI:

Git history

(Screenshots use demo data.)

  • System dashboard: counters, health checks (store/staging/index/queue/hooks/git), recent activity with source attribution, live updates via cheap polling (4 ms when nothing changed).
  • Per-project page: status + todos pinned, knowledge grouped by type.
  • Ranked search (same FTS5 index as the CLI), grouped/sortable/filterable list, bulk operations (supersede / re-scope / delete), supersede-chain navigation.
  • "What Claude sees": renders the exact SessionStart injection, with its size in bytes/tokens.
  • Review queue: candidates extracted by the optional local LLM wait here for human approval.
  • Git history: the store's timeline — commits touching store/ with colored per-commit diffs and a commit-from-the-UI button (store files only).

Optional: offline extraction with a local LLM

For sessions where the agent could not capture live, consolidate.py digests transcripts with a local model via Ollama (default qwen2.5:7b-instruct) and proposes candidates into the review queue. Honest finding from our testing: small models are noisy and over-confident, so nothing they produce is written without human approval.

ollama pull qwen2.5:7b-instruct
python3 consolidate.py --dry-run     # see what it would extract
python3 consolidate.py --write       # queue candidates -> review in the web UI

Configuration

Everything is overridable via environment variables — no config file needed:

VariableDefaultPurpose
MEM_DATA_DIRnext to the code; ~/.mem0ry4ai in plugin installswhere store/ + staging/ live (own git repo)
MEM_REDACT1set 0 to disable secret redaction on write paths
MEM_INJECT_BUDGET8000max bytes injected at SessionStart (critical rules always fit; cuts are announced)
MEM_WEB_PORT8841web UI port (server_web.sh)
MEM_PHPphp from PATHPHP binary (server + conformance test)
MEM_PYTHONpython3 from PATHPython binary used by the "What Claude sees" page
OLLAMA_URLhttp://localhost:11434Ollama endpoint for offline extraction
MEM_LLM_MODELqwen2.5:7b-instructmodel used by consolidate.py

Design notes

  • Two parsers, one contract: the Python engine (mem.py) and the PHP web UI read/write the same files. tests/conformance.py asserts both produce identical output — run it before committing parser changes.
  • Concurrency: atomic writes (tmp + rename), append-mostly files, WAL-free design — the store survives multiple sessions because markdown conflicts are rare and git catches the rest.
  • No commit chore: the SessionEnd hook auto-commits store/ (authored mem0ry4ai hook), so every session leaves a git checkpoint behind; the git page's button is for mid-session checkpoints with a custom message.
  • Your data is yours: if you fork this repo, do not commit your personal store/ upstream. The store is meant to be versioned in your clone, locally.

License

GPL-2.0-or-later — see LICENSE. We are giving back to the community.

Ver o original no GitHub

Bom para

Relacionados