MemoFS MCP Server
Persistent memory and virtual filesystem MCP server for AI agents.
Open source Repository Open in the app JSON README (API)
About
Persistent memory and virtual filesystem MCP server for AI agents.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- dev.memofs
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 1.3.0-beta.3
- Stars
- 6
- Forks
- 2
- Last push
- 2026-09-01T22:10:20Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:01:30
- Updated
- 2026-08-29 03:01:30
- Origin id
dev.memofs/mcp-server
README
<div align="center">
<img src="./assets/images/logo.svg" alt="MemoFS Logo" width="120" />
# MemoFS
Open-source, file-first memory runtime for AI agents.
</div>
<p align="center">
<a href="https://www.npmjs.com/package/@memofs/core"><img src="https://img.shields.io/npm/v/%40memofs%2Fcore?label=%40memofs%2Fcore&style=for-the-badge" alt="npm version" /></a>
<a href="https://github.com/memo-fs/memofs"><img src="https://img.shields.io/badge/status-beta-blue?style=for-the-badge" alt="Project status: Beta" /></a>
<a href="https://github.com/memo-fs/memofs/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/memo-fs/memofs/ci.yml?branch=main&style=for-the-badge&label=CI" alt="CI status" /></a>
<a href="https://docs.memofs.dev/"><img src="https://img.shields.io/badge/docs-online-blue?style=for-the-badge" alt="Docs" /></a>
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge" alt="MIT License" /></a>
</p>
---
## 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.
```text
.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
Reach first success in under a minute. No API keys, no database setup, no cloud required.
```bash
npm install @memofs/core
```
```ts
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.
To connect your coding agent (Cursor, Claude Code, etc.), use the stdio-compatible [@memofs/mcp-server](packages/mcp-server).
---
## Architecture
```text
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
```
The runtime resolves configuration from constructor options → env vars → `.memofs/config.json`.
Three runtime modes are supported: **`local`** (filesystem-only, default), **`hybrid`** (local + cloud sync with read/write policies), and **`memory`** (in-memory volatile, ideal for tests).
### Memory Intelligence
- **Code anchoring & drift detection** — bind memories to source files; stale memories are rank-demoted at recall time when anchored code changes.
- **Memory decay floors** — kind-specific expiry thresholds (30–365 days) transition old memories to `unverified` status.
- **Semantic GC** — archive deprecated memories to cold storage; restore on demand via `memofs restore`.
- **Session outcomes** — `success` / `failure` / `aborted` outcome on `complete()` governing durable memory promotion and workspace cleanup.
---
## Packages
MemoFS is structured as a monorepo containing 15 published public packages under the `@memofs/` scope. The CLI ships as `@memofs/cli` and installs the `memofs` command.
### Core Engine & Servers
| Package | Purpose |
| --- | --- |
| [`@memofs/core`](packages/core) | Core runtime, virtual AgentFS, graph engine, and hybrid recall router. |
| [`@memofs/cli`](packages/cli) | CLI tool for local and cloud memory workflows (`npx memofs`). |
| [`@memofs/server`](packages/server) | Self-hostable, OSS-deployable memory server for Node and Workers. |
| [`@memofs/mcp-server`](packages/mcp-server) | Model Context Protocol server exposing memory tools to AI agents. |
| [`@memofs/connectors`](packages/connectors) | Local ingestion framework plugins (Notion, GitHub). |
| [`@memofs/json-rpc`](packages/json-rpc) | Message schemas and validation for JSON-RPC 2.0. |
### Providers & Adapters
| Package | Purpose |
| --- | --- |
| [`@memofs/adapter-ai-sdk`](packages/adapter-ai-sdk) | Vercel AI SDK integration, runtime bridges, and tool definitions. |
| [`@memofs/adapter-openai`](packages/adapter-openai) | OpenAI embeddings adapter. |
| [`@memofs/adapter-voyage`](packages/adapter-voyage) | Voyage AI embedder and reranker adapter. |
| [`@memofs/adapter-transformers`](packages/adapter-transformers) | ONNX local embedder (Transformers.js) for zero-API-key hybrid recall. |
| [`@memofs/adapter-workers-ai`](packages/adapter-workers-ai) | Cloudflare Workers AI graph extractor adapter. |
| [`@memofs/adapter-r2`](packages/adapter-r2) | Cloudflare R2 Blob storage adapter. |
| [`@memofs/adapter-turso`](packages/adapter-turso) | Turso / libSQL metadata store adapter. |
### Development Tooling
| Package | Purpose |
| --- | --- |
| [`@memofs/testing`](packages/testing) | Shared contract tests, mocks, fakes, and fixtures. |
| [`@memofs/benchmark-kit`](packages/benchmark-kit) | Benchmark workloads and runners. |
---
## Open Source vs. MemoFS Cloud
The **core runtime is open source** (MIT) and fully functional locally. You do not need a cloud account to run MemoFS.
**MemoFS Cloud** is the memory plane for your agents: it keeps every machine, teammate, and agent on the same memory, and gives you a dashboard to see and govern it.
| Feature | Open source (this repo) | MemoFS Cloud |
| --- | --- | --- |
| Local file-first memory | ✅ | ✅ |
| CLI + stdio MCP server | ✅ | ✅ |
| All adapters (OpenAI, Voyage, etc.) | ✅ | ✅ |
| Hosted sync (keep memory in sync) | ✅ client | ✅ hosted |
| Team workspaces & access control | — | ✅ available |
| Memory dashboard (explore, consolidate) | — | ✅ available |
| Hosted managed MCP endpoint | — | ✅ available (Pro+) |
| Managed runtime (memory API over HTTPS) | — | Soon |
[Join the Cloud waitlist →](https://memofs.dev)
---
## Repository Structure
```text
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
```
---
## Workspace Commands
Run these command tasks from the repository root:
```bash
# 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
```
---
## Contributing
See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for details on formatting, testing, and pull requests.
For roadmap targets, see [`ROADMAP.md`](./ROADMAP.md).
For security reports, refer to [`SECURITY.md`](./SECURITY.md) — **do not** open public issues for security vulnerabilities.
---
## License
MIT. See [`LICENSE`](./LICENSE).