MemoFS

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

.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

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");

Your App / Agent / MCP client
        │
        ▼
    MemoFS   (local-first runtime)
      ├─ .read() / .write() / .recall()
      ├─ .snapshot.create() / .restore()
      ├─ AgentFS  (lease-locking & virtual paths)
      └─ .sync *  (Cloud sync pushes and pulls)

   read() / write() / recall() — core client methods
        │
        ▼
   .memofs/   (plain files on disk)
     ├─ memory/core.md      ├─ memory/notes.md
     ├─ events/*.jsonl      ├─ graph/{nodes,edges}.jsonl
     └─ snapshots/  manifest.json
        │   git-friendly, inspectable, versionable
        ▼   (optional)
   MemoFS Cloud

memofs/
├── apps/
│   └── docs/         # VitePress documentation (docs.memofs.dev)
├── packages/         # 15 published @memofs/* packages
├── tooling/          # Private @repo/* workspace build packages
├── benchmarks/       # Workspace benchmarking suite
├── examples/         # Runnable examples
└── package.json

# Install all dependencies
pnpm install

# Build all packages and applications
pnpm build

# Run TypeScript compilation checks
pnpm typecheck

# Run unit tests across all packages
pnpm test

# Run code style checks (Biome)
pnpm format-and-lint

# Fix linting and formatting issues automatically
pnpm format-and-lint:fix

# Build documentation locally
pnpm docs:build