# MemoFS MCP Server [Health: Active] **Category:** 🧠 Knowledge & Memory **Repository:** https://github.com/memo-fs/memofs **GitHub Stars:** 5 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/memofs-mcp-server ## Description Persistent memory and virtual filesystem MCP server for AI agents. ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "memofs-mcp-server": { "command": "npx", "args": ["-y","memofs"] } } ``` ## Documentation & README
MemoFS Logo # MemoFS Open-source, file-first memory runtime for AI agents.

npm version   Project status: Beta   CI status   Docs   MIT License

--- ## 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 │ └── .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](https://github.com/memo-fs/memofs/blob/HEAD/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`](https://github.com/memo-fs/memofs/blob/HEAD/packages/core) | Core runtime, virtual AgentFS, graph engine, and hybrid recall router. | | [`@memofs/cli`](https://github.com/memo-fs/memofs/blob/HEAD/packages/cli) | CLI tool for local and cloud memory workflows (`npx memofs`). | | [`@memofs/server`](https://github.com/memo-fs/memofs/blob/HEAD/packages/server) | Self-hostable, OSS-deployable memory server for Node and Workers. | | [`@memofs/mcp-server`](https://github.com/memo-fs/memofs/blob/HEAD/packages/mcp-server) | Model Context Protocol server exposing memory tools to AI agents. | | [`@memofs/connectors`](https://github.com/memo-fs/memofs/blob/HEAD/packages/connectors) | Local ingestion framework plugins (Notion, GitHub). | | [`@memofs/json-rpc`](https://github.com/memo-fs/memofs/blob/HEAD/packages/json-rpc) | Message schemas and validation for JSON-RPC 2.0. | ### Providers & Adapters | Package | Purpose | | --- | --- | | [`@memofs/adapter-ai-sdk`](https://github.com/memo-fs/memofs/blob/HEAD/packages/adapter-ai-sdk) | Vercel AI SDK integration, runtime bridges, and tool definitions. | | [`@memofs/adapter-openai`](https://github.com/memo-fs/memofs/blob/HEAD/packages/adapter-openai) | OpenAI embeddings adapter. | | [`@memofs/adapter-voyage`](https://github.com/memo-fs/memofs/blob/HEAD/packages/adapter-voyage) | Voyage AI embedder and reranker adapter. | | [`@memofs/adapter-transformers`](https://github.com/memo-fs/memofs/blob/HEAD/packages/adapter-transformers) | ONNX local embedder (Transformers.js) for zero-API-key hybrid recall. | | [`@memofs/adapter-workers-ai`](https://github.com/memo-fs/memofs/blob/HEAD/packages/adapter-workers-ai) | Cloudflare Workers AI graph extractor adapter. | | [`@memofs/adapter-r2`](https://github.com/memo-fs/memofs/blob/HEAD/packages/adapter-r2) | Cloudflare R2 Blob storage adapter. | | [`@memofs/adapter-turso`](https://github.com/memo-fs/memofs/blob/HEAD/packages/adapter-turso) | Turso / libSQL metadata store adapter. | ### Development Tooling | Package | Purpose | | --- | --- | | [`@memofs/testing`](https://github.com/memo-fs/memofs/blob/HEAD/packages/testing) | Shared contract tests, mocks, fakes, and fixtures. | | [`@memofs/benchmark-kit`](https://github.com/memo-fs/memofs/blob/HEAD/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`](https://github.com/memo-fs/memofs/blob/HEAD/CONTRIBUTING.md) for details on formatting, testing, and pull requests. For roadmap targets, see [`ROADMAP.md`](https://github.com/memo-fs/memofs/blob/HEAD/ROADMAP.md). For security reports, refer to [`SECURITY.md`](https://github.com/memo-fs/memofs/blob/HEAD/SECURITY.md) — **do not** open public issues for security vulnerabilities. --- ## License MIT. See [`LICENSE`](https://github.com/memo-fs/memofs/blob/HEAD/LICENSE).