MemoFS

Open-source, file-first memory runtime for AI agents.

What is MemoFS?

File-first memory runtime for AI agents. Store, recall, and synchronize memory using plain files on disk — local-first by default, with optional cloud sync.

Most AI memory systems are database-first, vendor-locked, hard to inspect, and hard to version. MemoFS inverts that: your agent's memory lives as Markdown and JSONL under a .memofs/ directory you can cat, git diff, and roll back.

.memofs/
├── config.json       # Workspace settings and engine routing
├── manifest.json     # Asset registry tracking and hashes
├── memory/
│   ├── core.md       # Durable, project-wide facts (Markdown)
│   └── notes.md      # Timestamped notes and logs (Markdown)
├── events/
│   └── conversations.jsonl # Chronological interactions for recall
├── graph/
│   ├── nodes.jsonl   # Entities extracted from memory
│   └── edges.jsonl   # Relational connections
├── archive/          # Cold storage for deprecated memories
│   └── <id>.json     # Full-fidelity archived memory records
└── snapshots/
    └── snap_123.json # Versioned restore checkpoints

Quick Start

MemoFS serves two primary paths: users running AI agents day-to-day and engineers building custom agents & runtimes.

Path A: For Users of AI Agents (Cursor, Claude Code, Codex, Copilot, Cline, etc.)

Initialize MemoFS in any project in under a minute. The CLI creates .memofs/, sets up project rules, pre-wires platform lifecycle hooks, and configures the local MCP server:

npx @memofs/cli init

Your agent now automatically inherits durable memory across sessions — zero manual prompting required.

Path B: For Builders of AI Agents & Runtimes

Embed the runtime directly into your TypeScript or Node.js agent architecture:

npm install @memofs/core

import { MemoFS } from "@memofs/core";
import { createNodeFsMemoryStore } from "@memofs/core/node-fs";

// Initialize a Node.js filesystem-backed memory store
const store = createNodeFsMemoryStore({
  rootDir: ".",
});

// Create the unified client
const memo = new MemoFS({
  store,
  projectId: "my-app",
  mode: "local",
});

// Read project-wide core memory (core.md)
const core = await memo.core.read();
console.log(core);

// Record a durable note (notes.md)
await memo.notes.record({
  content: "User prefers TypeScript with ESM modules.",
  kind: "preference",
});

// Recall works offline (lexical BM25 + fuzzy matching) with zero config
const hits = await memo.recall("TypeScript configuration");

To upgrade to semantic vector search, plug in an embedder adapter like OpenAI (@memofs/adapter-openai) or Voyage AI (@memofs/adapter-voyage). For zero-API-key local vector search, enable the ONNX embedder (@memofs/adapter-transformers) to run embeddings completely in-process.

Architecture

Your App / Agent / MCP client
        │
        ▼
    MemoFS   (local-first runtime)
      ├─ .read() / .write() / 

... [View full README on GitHub](https://github.com/memo-fs/memofs#readme)