Quick Start
Get up and running with MemoFS — the file-first memory runtime for AI agents.
MemoFS is the file-first memory runtime for AI agents. It stores decisions, architectural conventions, conversation context, and recall indexes directly as versioned Markdown and JSONL files in your project under .memofs/ — no database required.
Zero Infrastructure by Default
MemoFS runs completely locally with zero external dependencies. Deterministic BM25 keyword ranking and rule-based graph extraction work out of the box with 0 API keys. You can optionally attach embeddings or LLM adapters when you want enhanced semantic synthesis.
Choose Your Path
Using AI Agents
Connect Claude Code, Cursor, Codex, Copilot, Cline, or Aider in under 2 minutes.
Building Custom Agents
Embed @memofs/core directly in TypeScript, Node.js, or Edge agent runtimes.
Model Context Protocol (MCP)
Equip any MCP-compatible agent with context, recall, and persistence tools.
Self-Hosting & Server
Deploy MemoFS server on Node.js or Cloudflare Workers with local or cloud storage.
3-Minute Quickstart
Follow these steps to initialize and use MemoFS in any project:
1. Initialize MemoFS in your repository
Run the interactive CLI setup in the root of your project:
npx @memofs/cli initThe CLI scans your project, creates the .memofs/ directory, and scaffolds your project's core facts and agent instructions.
2. Inspect your .memofs/ memory files
All agent memory lives in plain, human-readable files that you can inspect, edit, and commit to git:
Git-Tracked Project Memory
Because memory is just markdown and JSONL in .memofs/, your agent's memory travels with git branches, pull requests, and across team members automatically.
3. Connect your AI agent
Choose how your agent communicates with MemoFS:
Add the MemoFS MCP server to Claude Code:
claude mcp add memofs npx -y @memofs/mcp-serverClaude Code will now automatically load context at task start (memofs.context), recall relevant decisions (memofs.recall), and persist learned facts (memofs.remember).
4. Verify your memory loop
Test that your memory is searchable and active:
# Query memory with hybrid keyword & semantic search
npx @memofs/cli context --query "authentication"
# Manually store a decision or constraint
npx @memofs/cli remember "Use strict TypeScript types without any" --kind decisionCore Pillars
File-First & Git-Native
No opaque databases. Human-readable Markdown and JSONL files versioned directly alongside your source code.
Deterministic Fallbacks
Works 100% offline out of the box with BM25 search and rule-based graph extraction. Zero API keys required.
Cloud & Team Sync
Optional real-time sync with Cloudflare R2, Turso, or MemoFS Cloud for distributed multi-agent teams.
Frequently Asked Questions
Next Steps
What is MemoFS? (Deep Dive)
Understand the architecture, mental model, and agent memory loop.
Explore Agent Cookbooks
Step-by-step setup guides for Claude Code, Cursor, Copilot, Cline, Aider, and more.
Core Concepts & Architecture
Learn how core memory, notes, recall indexes, and knowledge graphs interact.
API Reference
Full TypeScript SDK and CLI command reference.