{
  "markdown": "<div align=\"center\">\n\n<img src=\"./assets/images/logo.svg\" alt=\"MemoFS Logo\" width=\"120\" />\n\n# MemoFS\n\nOpen-source, file-first memory runtime for AI agents.\n\n</div>\n\n<p align=\"center\">\n  <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> &nbsp;\n  <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> &nbsp;\n  <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> &nbsp;\n  <a href=\"https://docs.memofs.dev/\"><img src=\"https://img.shields.io/badge/docs-online-blue?style=for-the-badge\" alt=\"Docs\" /></a> &nbsp;\n  <a href=\"./LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge\" alt=\"MIT License\" /></a>\n</p>\n\n---\n\n## What is MemoFS?\n\n**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.\n\nMost 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.\n\n```text\n.memofs/\n├── config.json       # Workspace settings and engine routing\n├── manifest.json     # Asset registry tracking and hashes\n├── memory/\n│   ├── core.md       # Durable, project-wide facts (Markdown)\n│   └── notes.md      # Timestamped notes and logs (Markdown)\n├── events/\n│   └── conversations.jsonl # Chronological interactions for recall\n├── graph/\n│   ├── nodes.jsonl   # Entities extracted from memory\n│   └── edges.jsonl   # Relational connections\n├── archive/          # Cold storage for deprecated memories\n│   └── <id>.json     # Full-fidelity archived memory records\n└── snapshots/\n    └── snap_123.json # Versioned restore checkpoints\n```\n\n---\n\n## Quick Start\n\nReach first success in under a minute. No API keys, no database setup, no cloud required.\n\n```bash\nnpm install @memofs/core\n```\n\n```ts\nimport { MemoFS } from \"@memofs/core\";\nimport { createNodeFsMemoryStore } from \"@memofs/core/node-fs\";\n\n// Initialize a Node.js filesystem-backed memory store\nconst store = createNodeFsMemoryStore({\n  rootDir: \".\",\n});\n\n// Create the unified client\nconst memo = new MemoFS({\n  store,\n  projectId: \"my-app\",\n  mode: \"local\",\n});\n\n// Read project-wide core memory (core.md)\nconst core = await memo.core.read();\nconsole.log(core);\n\n// Record a durable note (notes.md)\nawait memo.notes.record({\n  content: \"User prefers TypeScript with ESM modules.\",\n  kind: \"preference\",\n});\n\n// Recall works offline (lexical BM25 + fuzzy matching) with zero config\nconst hits = await memo.recall(\"TypeScript configuration\");\n```\n\nTo 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.\n\nTo connect your coding agent (Cursor, Claude Code, etc.), use the stdio-compatible [@memofs/mcp-server](packages/mcp-server).\n\n---\n\n## Architecture\n\n```text\nYour App / Agent / MCP client\n        │\n        ▼\n    MemoFS   (local-first runtime)\n      ├─ .read() / .write() / .recall()\n      ├─ .snapshot.create() / .restore()\n      ├─ AgentFS  (lease-locking & virtual paths)\n      └─ .sync *  (Cloud sync pushes and pulls)\n\n   read() / write() / recall() — core client methods\n        │\n        ▼\n   .memofs/   (plain files on disk)\n     ├─ memory/core.md      ├─ memory/notes.md\n     ├─ events/*.jsonl      ├─ graph/{nodes,edges}.jsonl\n     └─ snapshots/  manifest.json\n        │   git-friendly, inspectable, versionable\n        ▼   (optional)\n   MemoFS Cloud\n```\n\nThe runtime resolves configuration from constructor options → env vars → `.memofs/config.json`.\nThree runtime modes are supported: **`local`** (filesystem-only, default), **`hybrid`** (local + cloud sync with read/write policies), and **`memory`** (in-memory volatile, ideal for tests).\n\n### Memory Intelligence\n\n- **Code anchoring & drift detection** — bind memories to source files; stale memories are rank-demoted at recall time when anchored code changes.\n- **Memory decay floors** — kind-specific expiry thresholds (30–365 days) transition old memories to `unverified` status.\n- **Semantic GC** — archive deprecated memories to cold storage; restore on demand via `memofs restore`.\n- **Session outcomes** — `success` / `failure` / `aborted` outcome on `complete()` governing durable memory promotion and workspace cleanup.\n\n---\n\n## Packages\n\nMemoFS 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.\n\n### Core Engine & Servers\n\n| Package | Purpose |\n| --- | --- |\n| [`@memofs/core`](packages/core) | Core runtime, virtual AgentFS, graph engine, and hybrid recall router. |\n| [`@memofs/cli`](packages/cli) | CLI tool for local and cloud memory workflows (`npx memofs`). |\n| [`@memofs/server`](packages/server) | Self-hostable, OSS-deployable memory server for Node and Workers. |\n| [`@memofs/mcp-server`](packages/mcp-server) | Model Context Protocol server exposing memory tools to AI agents. |\n| [`@memofs/connectors`](packages/connectors) | Local ingestion framework plugins (Notion, GitHub). |\n| [`@memofs/json-rpc`](packages/json-rpc) | Message schemas and validation for JSON-RPC 2.0. |\n\n### Providers & Adapters\n\n| Package | Purpose |\n| --- | --- |\n| [`@memofs/adapter-ai-sdk`](packages/adapter-ai-sdk) | Vercel AI SDK integration, runtime bridges, and tool definitions. |\n| [`@memofs/adapter-openai`](packages/adapter-openai) | OpenAI embeddings adapter. |\n| [`@memofs/adapter-voyage`](packages/adapter-voyage) | Voyage AI embedder and reranker adapter. |\n| [`@memofs/adapter-transformers`](packages/adapter-transformers) | ONNX local embedder (Transformers.js) for zero-API-key hybrid recall. |\n| [`@memofs/adapter-workers-ai`](packages/adapter-workers-ai) | Cloudflare Workers AI graph extractor adapter. |\n| [`@memofs/adapter-r2`](packages/adapter-r2) | Cloudflare R2 Blob storage adapter. |\n| [`@memofs/adapter-turso`](packages/adapter-turso) | Turso / libSQL metadata store adapter. |\n\n### Development Tooling\n\n| Package | Purpose |\n| --- | --- |\n| [`@memofs/testing`](packages/testing) | Shared contract tests, mocks, fakes, and fixtures. |\n| [`@memofs/benchmark-kit`](packages/benchmark-kit) | Benchmark workloads and runners. |\n\n---\n\n## Open Source vs. MemoFS Cloud\n\nThe **core runtime is open source** (MIT) and fully functional locally. You do not need a cloud account to run MemoFS.\n\n**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.\n\n| Feature | Open source (this repo) | MemoFS Cloud |\n| --- | --- | --- |\n| Local file-first memory | ✅ | ✅ |\n| CLI + stdio MCP server | ✅ | ✅ |\n| All adapters (OpenAI, Voyage, etc.) | ✅ | ✅ |\n| Hosted sync (keep memory in sync) | ✅ client | ✅ hosted |\n| Team workspaces & access control | — | ✅ available |\n| Memory dashboard (explore, consolidate) | — | ✅ available |\n| Hosted managed MCP endpoint | — | ✅ available (Pro+) |\n| Managed runtime (memory API over HTTPS) | — | Soon |\n\n[Join the Cloud waitlist →](https://memofs.dev)\n\n---\n\n## Repository Structure\n\n```text\nmemofs/\n├── apps/\n│   └── docs/         # VitePress documentation (docs.memofs.dev)\n├── packages/         # 15 published @memofs/* packages\n├── tooling/          # Private @repo/* workspace build packages\n├── benchmarks/       # Workspace benchmarking suite\n├── examples/         # Runnable examples\n└── package.json\n```\n\n---\n\n## Workspace Commands\n\nRun these command tasks from the repository root:\n\n```bash\n# Install all dependencies\npnpm install\n\n# Build all packages and applications\npnpm build\n\n# Run TypeScript compilation checks\npnpm typecheck\n\n# Run unit tests across all packages\npnpm test\n\n# Run code style checks (Biome)\npnpm format-and-lint\n\n# Fix linting and formatting issues automatically\npnpm format-and-lint:fix\n\n# Build documentation locally\npnpm docs:build\n```\n\n---\n\n## Contributing\n\nSee [`CONTRIBUTING.md`](./CONTRIBUTING.md) for details on formatting, testing, and pull requests.\nFor roadmap targets, see [`ROADMAP.md`](./ROADMAP.md).\n\nFor security reports, refer to [`SECURITY.md`](./SECURITY.md) — **do not** open public issues for security vulnerabilities.\n\n---\n\n## License\n\nMIT. See [`LICENSE`](./LICENSE).\n",
  "bytes": 8832,
  "sha": "ee01a8171968ddf9163b78b1792f9e555ce96fe10d25071260bafe85b0d15715",
  "repo_slug": "memo-fs/memofs",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_dev_memofs_mcp_server_0ff93d2e/readme"
}