agentic-memory

# Memory Fabric

<!-- mcp-name: io.github.elViRafa/memory-fabric -->

[![CI](https://github.com/elViRafa/agentic-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/elViRafa/agentic-memory/actions/workflows/ci.yml)

**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.1.1 — project directives: hand-curated steering distributed to every agent vendor.
[Live on PyPI](https://pypi.org/project/memory-fabric/).**
Core CLI and MCP tools work end-to-end. See [`ROADMAP.md`](ROADMAP.md) for what
shipped, what's in progress, and what's next.

---

## Demo

![Memory Fabric CLI demo — init, write a memory, and a commit captures itself](docs/demo-cli.gif)

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`](DEMO.md) for the full video.

---

## Privacy — no telemetry

Memory Fabric collects **nothing**. No telemetry, 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. This is a deliberate guarantee, not a default we might change.

---

## Installation

### From PyPI (recommended)

Requires Python ≥ 3.11.

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

Or with plain `pip` (inside a virtual environment):

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

Zero-install one-off run (requires [`uv`](https://docs.astral.sh/uv/)):

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

### From GitHub (latest, pre-release)

```sh
# 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):

```sh
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
   # 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
   # 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
   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:

```sh
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

```sh
ai-memory init
```

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

### 2. Check health

```sh
ai-memory doctor
```

### 3. Evaluate memory quality

```sh
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:

```text
.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

```sh
ai-memory query "authentication"
```

### 5. Run maintenance (Dreaming)

```sh
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:

```sh
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

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22memory-fabric%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22memory-fabric%5Bmcp%5D%22%2C%22memory-fabric-mcp%22%5D%7D)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](vscode-insiders:mcp/install?%7B%22name%22%3A%22memory-fabric%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22memory-fabric%5Bmcp%5D%22%2C%22memory-fabric-mcp%22%5D%7D)
[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=memory-fabric&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJtZW1vcnktZmFicmljW21jcF0iLCJtZW1vcnktZmFicmljLW1jcCJdfQ==)

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`](https://docs.astral.sh/uv/).

| Client | Command |
|---|---|
| Claude Code | `ai-memory install --client claude-code` |
| Claude Desktop | `ai-memory install --client claude-desktop` |
| VS Code | `ai-memory install --client vscode` |
| Cursor | `ai-memory install --client cursor` |
| Windsurf | `ai-memory install --client windsurf` |
| Codex | `ai-memory install --client codex` |
| Antigravity | `ai-memory install --client antigravity` |
| Gemini CLI | `ai-memory install --client gemini-cli` |
| Cline | `ai-memory install --client cline` |
| All detected clients | `ai-memory install --client all` |

Add `--project` to write project-scoped config instead of the global/user config
(where the client