🧠 MemFS

A knowledge graph management system based on MCP server-memory, deeply refactored with filesystem-inspired design

💡 Acknowledgments: Original @modelcontextprotocol/server-memory
Inspired by it, though heavily reimagined.

🎯 One-Line Description

Bringing modern filesystem concepts to knowledge graph management, combined with BM25 + fuzzy search for intelligent retrieval, designed for LLM-assisted humanities and social sciences research.

📖 中文版文档: docs/README_zh-CN.md

🚀 Quick Start

Prerequisites

# Check Node.js version
node --version  # Must be v22.0.0 or higher

Installation & Run

Quickest way (npx):

npx @qty/memfs

Or clone and run:

# 1. Clone or download the project
cd MemFS

# 2. Install dependencies
npm install

# 3. Run server
node index.js

# Or specify custom storage directory
MEMORY_DIR=~/my-knowledge

# Enable Git auto-sync (auto-commits on every save)
GITAUTOCOMMIT=true node index.js

Configure as MCP Server

OpenCode format:

{
  "mcpServers": {
    "memory": {
      "type": "local",
      "command": ["npx", "-y", "@qty/memfs"],
      "enabled": true
    }
  }
}

VSCode / ClaudeCode / Cherry Studio / AstrBot format:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@qty/memfs"],
      "enabled": true
    }
  }
}

📰 What's New in 2.4.12

Git Auto-Commit

New GITAUTOCOMMIT=true environment variable — every operation auto-commits to Git:

auto-commit:[createEntity "Weber"] at [utc:2026-03-28T12:34:56.789Z] [tz:Asia/Shanghai]

searchNode Refactoring

• Response simplified to { entities, observations, relations }
• Removed searchMode field
• observations now includes updatedAt
• Related entities count limited by limit
• Unified tokenization: 2~(n-1) gram, no language detection
• 2-gram penalty ×0.5: short tokens no longer over-match
• Field weights centralized in DEFAULT_FIELD_WEIGHTS
• definitionSource added to search index
• Relation type matching boost

Operation Return Refactoring

• Write operation messages simplified (less LLM token consumption)
• Delete operations return full data for potential undo
• deleteObservation now uses ID-based input

Auxiliary Tools

• New getConsole tool to retrieve buffered logs

📖 Core Concepts

💡 Core Design Philosophy

1. Transformer-Ready: On-Demand Retrieval

flowchart TD
    LLM["LLM"]
    ATT["Attention Mechanism"]
    MCP["MCP Protocol"]
    MEM["MemFS\nOn-demand structured data"]

    LLM --> ATT --> MCP --> MEM
    MEM -.-> |Returns results| LLM

Core principle: Don't stuff all knowledge into context—retrieve on demand.

2. Lightweight Design

3. Local JSONL Storage

{"type":"entity","name":"Weber","entityType":"person","definition":"German sociologist","observationIds":[1,2]}
{"type":"observation","id":1,"content":"Author of 'The Protestant Ethic'","createdAt":{"utc":"2026-02-08T13:53:07Z","timezone":"Asia/Shanghai"}}
{"type":"relation","from":"Weber","to":"Durkheim","relationType":"contemporary"}

Advantages: Editable with any text editor, Git-version-controllable, printable.

4. Humanities & Social Sciences Customization

📦 Complete API Tools (16 total)

Create

Read

Update

Delete

Auxiliary

🔍 Hybrid Search (searchNode)

Core Features

Parameters

// Default hybrid search
await searchNode("functionalism");  // BM25 + Fuzzy

// Traditional keyword search
await searchNode("functionalism", { basicFetch: true });

// Custom parameters
await searchNode("sociology", {
    limit: 15,          // Return count
    bm25Weight: 0.7,    // BM25 weight
    fuzzyWeight: 0.3,   // Fuzzy search weight
    minScore: 0.01      // Minimum relevance threshold
});

Field Weights

🔧 Filesystem-Inspired Design

Architecture Analogy

Observation Sharing

// Create two entities sharing the same observation
await createEntity([
  { name: "Zhang San", observations: ["Programmer"] },
  { name: "Li Si", observations: ["Programmer"] }
]);

// Under the hood: same observation ID is reused
{
  entities: [
    { name: "Zhang San", observationIds: [1] },
    { name: "Li Si", observationIds: [1] }
  ],
  observations: [
    { id: 1, content: "Programmer" }
  ]
}

Copy-on-Write

// Update a shared observation
await updateNode({
  entityName: "Zhang San",
  observationUpdates: [
    { oldContent: "Programmer", newContent: "Senior Programmer" }
  ]
});

// Result: Zhang San gets new observation, Li Si keeps original
{
  observations: [
    { id: 1, content: "Programmer" },      // Li Si uses
    { id: 2, content: "Senior Programmer" } // Zhang San's new observation
  ]
}

📁 Data Format

JSONL Storage

{"type":"entity","name":"Weber","entityType":"person","definition":"German sociologist","definitionSource":"Wikipedia","observationIds":[1,2]}
{"type":"entity","name":"Durkheim","entityType":"person","definition":"French sociologist","definitionSource":"Wikipedia","observationIds":[3]}
{"type":"observation","id":1,"content":"Author of 'The Protestant Ethic'","createdAt":{"utc":"2026-02-08T13:53:07Z","timezone":"Asia/Shanghai"}}
{"type":"observation","id":2,"content":"Contemporary with Durkheim and Marx","createdAt":{"utc":"2026-02-08T14:00:00Z","timezone":"Asia/Shanghai"},"updatedAt":{"utc":"2026-02-09T10:30:00Z","timezone":"Asia/Shanghai"}}
{"type":"observation","id":3,"content":"Author of 'The Division of Labor in Society'","createdAt":{"utc":"2026-02-08T15:00:00Z","timezone":"Asia/Shanghai"}}
{"type":"relation","from":"Weber","to":"Durkheim","relationType":"contemporary"}

Storage Locations

Environment Variables

🔄 Git Auto-Sync

When enabled, every save to the memory file is automatically committed to Git for version control.

# Enable Git auto-commit
GITAUTOCOMMIT=true node index.js

# Or in MCP config
{
  "environment": {
    "MEMORY_DIR": "/path/to/data",
    "GITAUTOCOMMIT": "true"
  }
}

Commit Format

auto-commit:[operationContext] at [utc:YYYY-MM-DDTHH:mm:ss.SSSZ] [tz:Asia/Shanghai]

Example:

auto-commit:[createEntity "Weber"] at [utc:2026-03-22T09:15:30.123Z] [tz:Asia/Shanghai]
auto-commit:[updateNode "Durkheim"] at [utc:2026-03-22T09:16:45.456Z] [tz:Asia/Shanghai]
auto-commit:[deleteRelation "Weber"→"Durkheim"] at [utc:2026-03-22T09:17:00.789Z] [tz:Asia/Shanghai]

auto-sync: (operation_type "details") at UTC YYYY-MM-DDTHH:mm:ss.SSSZ

Example:

auto-sync: (createEntity "Weber") at UTC 2026-03-22T09:15:30.123Z auto-sync: (updateNode "Durkheim") at UTC 2026-03-22T09:16:45.456Z auto-sync: (deleteRelation "Weber"→"Durkheim") at UTC 2026-03-22T09:17:00.789Z

### View Commit History

Use `getConsole` tool:

```javascript
await getConsole()
// Returns text content with buffered logs and Git commits prefixed by "[Git]"

📦 Legacy Version

The v1.3.0 code is available on the legacy branch:

git clone https://github.com/Qtgcy08/MemFS.git
cd MemFS
git checkout legacy

If you're using MEMORY_FILE_PATH, please migrate to MEMORY_DIR before upgrading.

🧪 Testing

# Full test suite (22 tests)
node test_mcp_full.mjs

# Git Sync tests
node test_gitsync.mjs

⚙️ Comparison with Original MCP Memory

📚 Design Philosophy

What? You're still reading? Well, alright.

Honestly, this project started because:

1. LLM context is limited — can't stuff all knowledge into prompts
2. Filesystem is a great invention — handling "multiple data sharing same content" is mature
3. Humanities research has special needs — concepts, literature, citation relationships
4. Controllability > SOTA — no need for black-box vector models

So:

• Borrow filesystem wisdom: inode table, hard links, copy-on-write
• Search uses BM25 + Fuzzy: lightweight, explainable, transparent, controllable
• Expose as tools: 16 MCP tools, LLM calls on demand

Result? — A quiet, efficient, unobtrusive knowledge management tool.

📄 License

Apache License 2.0

Manage knowledge the filesystem way—bringing order to chaos.