Memory Fabric

File-first, local-first memory layer for MCP-compatible AI coding assistants.

Memory Fabric gives AI tools like Claude Code, Cursor, and GitHub Copilot a consistent, project-aware context layer without locking you into one model, editor, cloud provider, or operating system.

Memory is stored as human-readable Markdown with YAML frontmatter. No vector database. No cloud account. No embeddings required.

Features

• MCP-native: exposes memory tools through the standard Model Context Protocol
• File-first: Markdown files are the source of truth, inspectable and commit-ready
• Local-first: core reads and writes work offline
• Store-first: facts live in memory-store/, one per file; root maps (architecture.md, decisions.md, ...) are generated views rebuilt by Dreaming, never hand-written
• Captures itself: every git commit is recorded as episodic memory automatically — no agent cooperation required — via an opt-in post-commit hook
• Git-native merge: an optional custom merge driver lets two branches' memory merge as cleanly as their code, instead of conflicting on a shared timestamp line
• Self-verifying: memories can cite the file/line/commit they depend on; ai-memory verify flags citations that rotted
• Learns from failure: write_failure_memory_tool deduplicates repeat occurrences of the same error into one growing record instead of scattering near-duplicates
• Secret-safe: API keys and credentials are redacted before writing
• Token-budget aware: assembles context within limits; never slices files mid-document
• Quality eval: scores memory usefulness and Dreaming before/after results locally
• Unicode-safe: works with any human language
• Graceful degradation: works without rg, git hooks, or Dreaming configured

Status

v1.4.1 — field-store write/read hygiene (live handoffs, query packs, doctor smells) on top of the local field diary. Live on PyPI. Core CLI and MCP tools work end-to-end. See ROADMAP.md for what shipped, what's in progress, and what's next.

Demo

The CLI and self-capture flow: initialize a project, write a memory as a plain Markdown file in your repo, and watch a git commit record itself as episodic memory with no agent cooperation. The cross-tool moment — an agent writes memory in one tool and a different tool reads it back — is storyboarded in DEMO.md for the full video.

Privacy — no telemetry

Memory Fabric never sends data anywhere. There is no account, no cloud, no analytics, no phone-home. The core read and write paths make no network calls at all; the only optional network requests are a PyPI version-drift check and an LLM-provider preflight, both of which you can turn off with --offline. Your memory is plain Markdown in your own git history — it never leaves your machine unless you push it.

An optional, off-by-default field diary can record operational counts on your machine after you run ai-memory diary approve. That is not the session journal, and it is not telemetry: nothing is transmitted. MEMORY_FABRIC_DIARY=0 is a kill switch. This is a deliberate guarantee, not a default we might change.

Installation

From PyPI (recommended)

Requires Python ≥ 3.11.

pipx install memory-fabric          # CLI only
pipx install "memory-fabric[mcp]"   # CLI + MCP server

Or with plain pip (inside a virtual environment):

pip install memory-fabric          # CLI only
pip install "memory-fabric[mcp]"   # CLI + MCP server

Zero-install one-off run (requires uv):

uvx --from "memory-fabric[mcp]" memory-fabric-mcp   # starts the MCP server on stdio

From GitHub (latest, pre-release)

# CLI only
pipx install "git+https://github.com/elViRafa/agentic-memory.git"

# CLI + MCP server
pipx install "memory-fabric[mcp] @ git+https://github.com/elViRafa/agentic-memory.git"

Or with plain pip (inside a virtual environment):

pip install "git+https://github.com/elViRafa/agentic-memory.git"          # CLI only
pip install "memory-fabric[mcp] @ git+https://github.com/elViRafa/agentic-memory.git"  # + MCP

Upgrading

Because Memory Fabric is in active development, we recommend upgrading regularly:

1. Upgrade the Package:

   sh

   Copy

   # If installed via pipx:
   pipx upgrade memory-fabric
   
   # If installed in a virtual environment via pip:
   pip install --upgrade "memory-fabric[mcp]"
   
   # If installed from GitHub (pre-release):
   pipx install --force "memory-fabric[mcp] @ git+https://github.com/elViRafa/agentic-memory.git"
   

2. Refresh the MCP client config (uvx installs): If your client config launches the server via uvx (the default written by older ai-memory install runs), uv serves the build it cached the first time and never re-resolves an unpinned spec — restarting the client is not enough and can leave the server several releases behind without any signal. After upgrading, either:

   sh

   Copy

   # Re-write the client config (now pins the exact installed version, or points
   # at the local memory-fabric-mcp binary when one sits next to the CLI):
   ai-memory install --client <your-client> --project
   
   # ...or drop the stale cached build so uvx re-resolves:
   uv cache clean memory-fabric
   

   ai-memory doctor warns when the local version drifts from the latest on PyPI or when a different ai-memory installation shadows this one on PATH.

3. Restart MCP Clients: After upgrading, restart your IDE (Cursor, VS Code) or assistant process (Claude Code) to ensure the client reloads the updated memory-fabric-mcp server.

4. Refresh Local Projects (Optional): If you have projects initialized with older versions of Memory Fabric, navigate to the project directory and run:

   sh

   Copy

   ai-memory init --install-hooks
   

   This will safely refresh starter templates and local git hook integration to the latest format without overwriting your existing memory markdown files.

Windows terminals: the CLI emits UTF-8 (memory content legitimately contains em-dashes and bullets). Windows Terminal and PowerShell 7 render it out of the box; on legacy consoles (PowerShell 5.1 with an OEM code page) set chcp 65001 or PYTHONUTF8=1 if you see replacement characters.

Or clone and install in editable mode for local development:

git clone https://github.com/elViRafa/agentic-memory.git
cd agentic-memory
pip install -e .          # CLI only
pip install -e ".[mcp]"   # CLI + MCP server

Quick Start

1. Initialize a project

ai-memory init

Creates .ai-memory/ in the current directory with starter sections and a .gitignore.

2. Check health

ai-memory doctor

3. Evaluate memory quality

ai-memory eval
ai-memory eval --json

eval scores whether memories are useful for coding assistants. It checks section coverage, starter-template content, summary quality, metadata, retrieval readiness, and likely secrets.

If .ai-memory/ exists, reports are saved under ignored local files:

.ai-memory/evals/latest.json
.ai-memory/evals/latest.md
.ai-memory/evals/<timestamp>-memory.json
.ai-memory/evals/<timestamp>-memory.md

If .ai-memory/ does not exist yet, eval prints a pre-init report only and creates no files.

4. Query memory

ai-memory query "authentication"

5. Run maintenance (Dreaming)

ai-memory dream --mode light
ai-memory dream --mode deep

Dreaming creates a snapshot before maintenance. You can evaluate whether a Dreaming run improved memory quality:

ai-memory eval --dream latest
ai-memory dream --mode light --eval

Dream eval compares the pre-dream snapshot to current memory and reports score delta, changed files, improvements, and regressions.

MCP Server — Install

One command per client. Safe to re-run: merges with your existing config, never overwrites it, and backs up the original file if it can't be parsed.

One-click install

These call uvx --from "memory-fabric[mcp]" memory-fabric-mcp under the hood — same canonical invocation as ai-memory install, just without the CLI step. Requires uv.