FractalMem

Project memory you can inspect, update, and resume.

FractalMem keeps a project's current objective, constraints, decisions and next actions in local Markdown/HTML files. Developers and coding agents can read the sources, safely update them, and resume work through a CLI or MCP server.

Start with the local quickstart and executable demo. For evaluation, see the developer pilot kit and benchmark limitations.

FractalMem is designed to run as:

• a local fm CLI
• a stdio MCP server for agent clients
• a Codex plugin
• a Claude Code plugin

The solution is split into:

• FractalMemory.Core: domain, services, filesystem logic, indexing, search, export, validation, and formatting
• FractalMemory.Cli: fm command-line interface over the core services
• FractalMemory.McpServer: optional MCP server wrapper over the same core services

Concept

Each memory node behaves like a chapter:

• index.md or index.html: front door, summary, navigation
• state.md or state.html: current working truth
• timeline.md or timeline.html: chronological updates
• decisions.md or decisions.html: important decisions and rationale
• children/: nested subnodes
• artifacts/: supporting markdown and HTML files

Files are the source of truth. Index files are accelerators, not authorities.

Solution Layout

FractalMemory.sln

src/
  FractalMemory.Core/
  FractalMemory.Cli/
  FractalMemory.McpServer/

tests/
  FractalMemory.Core.Tests/
  FractalMemory.Cli.Tests/

plugins/
  codex-fractalmem/
  claude-fractalmem/

Build

Requirements:

• .NET SDK 10.0.100 or later

Build everything:

dotnet build FractalMemory.sln

Run all tests:

dotnet test --solution FractalMemory.sln

Run The CLI

Run from source:

dotnet run --project src/FractalMemory.Cli -- init

Build the binary and run fm directly:

dotnet build src/FractalMemory.Cli
./src/FractalMemory.Cli/bin/Debug/net10.0/fm init

Pack local .NET tools:

dotnet pack src/FractalMemory.Cli
dotnet pack src/FractalMemory.McpServer

Install the current source checkout into an isolated tool directory:

python3 scripts/install-local.py
python3 scripts/demo.py

The scripts require Python 3.11+ in addition to the .NET SDK. See the quickstart for Windows commands, MCP configuration and installation options. This path does not depend on a published NuGet release.

Example CLI Commands

• fm init
• fm node create projects/fractal-memory-cli
• fm node create projects/design-notes --format html
• fm open projects/fractal-memory-cli
• fm open projects/fractal-memory-cli --depth 2
• fm search "context bloat"
• fm export projects/fractal-memory-cli --mode compact
• fm handoff create projects/fractal-memory-cli
• fm recent
• fm index refresh
• fm validate

Capture, Maintain and Resume Memory

Use fm read and hash-checked fm update / fm append to record working state and decisions safely. fm attention surfaces stale or incomplete memory, fm context builds bounded source-linked context, and fm resume reports changes since the node's latest handoff. fm doctor --repair rebuilds indexes; fm import previews existing notes before saving them. All commands support --json.

See Memory workflows for CLI examples, MCP equivalents, source access, decision supersession, review dates, import behavior and the precise context-budget contract.

Agent Plugins

FractalMem exposes the same core operations through a stdio MCP server:

fractalmem-mcp

The MCP server resolves the repository from its current working directory, or from FRACTALMEM_REPOSITORY_ROOT when an agent client launches it from another directory.

Installable plugin sources live under:

• plugins/codex-fractalmem/
• plugins/claude-fractalmem/

Marketplace metadata lives under:

• .agents/plugins/marketplace.json
• .claude-plugin/marketplace.json

See docs/plugins.md for plugin packaging and local installation notes.

Repository Layout

fm init creates:

.fractal-memory/
  config.yaml
  root/
    index.md
    state.md
    timeline.md
    decisions.md
    children/
    artifacts/
  projects/
  people/
  systems/
  research/
  handoffs/
  indexes/
    aliases.yaml
    tags.yaml
    paths.yaml
  templates/
    node/
      index.md
      state.md
      timeline.md
      decisions.md
  archive/

Each created node contains:

<node>/
  index.md      # or index.html when created with --format html
  state.md      # or state.html
  timeline.md   # or timeline.html
  decisions.md  # or decisions.html
  children/
  artifacts/

CLI Behavior Summary

• init creates the repository, config, templates, root files, and index stubs.
• node create normalizes and validates the path, creates the standard node contract as markdown or HTML, and refreshes indexes when both indexing and refresh_on_write are enabled.
• open supports layered retrieval with depth 0..3 and optional focused views.
• search ranks exact path, title, alias, tag, then markdown content matches, with optional path scoping.
• export emits AI-friendly structured output with stable source labels.
• handoff create writes resumable handoff markdown into the configured handoff directory (by default .fractal-memory/handoffs/).
• recent surfaces recently modified nodes for work resumption.
• index refresh rebuilds aliases, tags, and paths from filesystem truth.
• validate reports hard errors and warnings for structure, metadata, and stale indexes.

Retrieval and recovery

• open --view state and depth 3 include the complete state document. Depth 2 selects populated working sections and marks an abridged state explicitly (stateTruncated in MCP results).
• Markdown search and export citations use original file line numbers, including front matter. HTML retains headings and lists for structured retrieval; HTML citations include paths and section headings without generated line numbers.
• Scoped searches load only the requested branch, so malformed content in another branch does not block them.
• Node creation validates configuration and stages a complete, parsed node before publishing it. Failed writes clean up their staging directory; validation reports incomplete scaffolds left by older versions.
• index refresh reads source documents, includes front matter in cache invalidation, and repairs damaged caches. Older cache formats are ignored on reads and upgraded on the next refresh. Unchanged valid cache files retain their modification times.
• Undefined numeric depth, view, format, and export-mode values are rejected.

Run The Optional MCP Server

The MCP server is optional. The CLI does not depend on it.

Run the stdio MCP server:

dotnet run --project src/FractalMemory.McpServer

By default, the server resolves repositories from its current working directory by walking upward for .fractal-memory/config.yaml, just like the CLI.

If the MCP host launches the server outside the repository, set FRACTALMEM_REPOSITORY_ROOT to the repository root:

FRACTALMEM_REPOSITORY_ROOT=/absolute/path/to/workspace \
dotnet run --project src/FractalMemory.McpServer

Configuration

.fractal-memory/config.yaml controls retrieval, indexing, metadata, handoffs, and validation:

• default_depth is used by CLI and MCP open calls when no depth is supplied.
• default_export_mode is used by CLI and MCP exports when no mode is supplied.
• indexing.enabled enables indexes; indexing.refresh_on_write controls automatic refresh after node creation.
• metadata.front_matter controls whether new Markdown nodes include YAML front matter.
• handoffs.directory selects a relative directory inside .fractal-memory/.
• retrieval limits must be positive integers.

Configured storage directories cannot be absolute or contain . or .. traversal. Symbolic links and reparse points inside .fractal-memory/ are rejected so CLI and MCP operations cannot escape the repository boundary.

MCP Surface

The capture, freshness, context, resume, repair and import tools are documented in Memory workflows. memory_read and memory_context also return native links to full source resources.

Tools:

• memory_open(path, depth?, view?)
• memory_search(query, limit?, scope?)
• memory_recent(days?, limit?, scope?)
• memory_export(path, mode?)
• memory_handoff_create(path)
• memory_index_refresh()
• memory_validate()

Resources:

• memory://root/index
• memory://node/index/{path}
• memory://node/state/{path}
• memory://handoffs/latest

For dynamic node resources, pass the repository-relative node path URL-encoded in {path}, for example projects%2Ffractal-memory-cli.

Prompts:

• resume_project
• summarize_node
• create_handoff_from_node

Conceptual MCP Usage

Typical agent workflow:

1. Call memory_open("projects/fractal-memory-cli", depth: 1) for orientation.
2. Call memory_recent(scope: "projects/fractal-memory-cli") to inspect recent movement.
3. Call memory_export("projects/fractal-memory-cli", mode: "standard") when prompt-ready structured context is needed.
4. Call memory_handoff_create("projects/fractal-memory-cli") before handing work to another agent or later session.

Notes

• Core logic is independent of both CLI and MCP.
• YAML front matter parsing is isolated behind IFrontMatterParser.
• The implementation is built for standard .NET 10 JIT execution first, while keeping the architecture relatively AOT-friendly.
• There is no database, network storage, telemetry, GUI, or cloud dependency in the core MVP.
• Benchmarking lives separately at https://github.com/agentqi/fractal-memory-bench.
• Release and branch-protection setup is documented in docs/releasing.md.