MCP 服务器

@memofs/mcp-server

@memofs/mcp-server lets AI coding agents (Claude Code, Claude Desktop, Codex, Cursor, opencode, Gemini CLI, GitHub Copilot, Zed, and any other MCP client) securely read and write MemoFS memory through standard Model Context Protocol tools.

README

MemoFS

Open-source, file-first memory for AI applications and agents.

</div>

What is MemoFS?

File-first memory for AI applications and 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
└── 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.

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.

To connect your coding agent (Cursor, Claude Code, etc.), use the stdio-compatible @memofs/mcp-server.

Architecture

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).

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`	Core runtime, virtual AgentFS, graph engine, and hybrid recall router.
`@memofs/cli`	CLI tool for local and cloud memory workflows (`npx memofs`).
`@memofs/server`	Self-hostable, OSS-deployable memory server for Node and Workers.
`@memofs/mcp-server`	Model Context Protocol server exposing memory tools to AI agents.
`@memofs/connectors`	Local ingestion framework plugins (Notion, GitHub).
`@memofs/json-rpc`	Message schemas and validation for JSON-RPC 2.0.

Providers & Adapters

Package	Purpose
`@memofs/adapter-ai-sdk`	Vercel AI SDK integration, runtime bridges, and tool definitions.
`@memofs/adapter-openai`	OpenAI embeddings adapter.
`@memofs/adapter-voyage`	Voyage AI embedder and reranker adapter.
`@memofs/adapter-transformers`	ONNX local embedder (Transformers.js) for zero-API-key hybrid recall.
`@memofs/adapter-workers-ai`	Cloudflare Workers AI graph extractor adapter.
`@memofs/adapter-r2`	Cloudflare R2 Blob storage adapter.
`@memofs/adapter-turso`	Turso / libSQL metadata store adapter.

Development Tooling

Package	Purpose
`@memofs/testing`	Shared contract tests, mocks, fakes, and fixtures.
`@memofs/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 →

Repository Structure

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:

# 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 for details on formatting, testing, and pull requests. For roadmap targets, see ROADMAP.md.

For security reports, refer to SECURITY.md — do not open public issues for security vulnerabilities.

License

MIT. See LICENSE.