Memory Fabric

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.5 — field diary pack/analyze and live posture pinning. [Live on PyPI](https://pypi.org/project/memory-fabric/). 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. ai-memory diary pack builds a shareable folder under the app data field-packs/ directory (Windows: %APPDATA%/memory-fabric/field-packs/); you copy that folder yourself. ai-memory diary analyze scores product signals from a pack or the local diary. 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:

   # 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"

1. 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:

   # 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 --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.

1. 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.

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

   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/ -memory.json .ai-memory/evals/ -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.

Add --project to write project-scoped config instead of the global/user config (where the client supports it). Add --dry-run to preview the change as a unified diff without writing anything. Add --uninstall to remove only the memory-fabric entry, leaving everything else in the file untouched.

Available MCP Tools