Memory Mcp 1file

MCP文档知识

提供方 pomazanbohdan

文档知识 未标注 API Key 社区 / 第三方 CursorCodexZed

A high-performance, pure Rust Model Context Protocol (MCP) server that provides persistent, semantic, and graph-based memory for AI agents.

一句话选型结论

按资料字段整理

Memory Mcp 1file 属于文档知识类 MCP 服务器,传输方式未标注,API Key,可直接接入 Cursor、Codex、Zed,没有现成安装命令,需按官方文档接入。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类文档知识 传输方式未标注 鉴权API Key 部署方式未标注
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

文档知识
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

vector search knowledge graph code indexing

支持客户端

适用场景

vector searchknowledge graphcode indexing

安装与配置

未标注 API Key
上游未给出传输方式
  1. 1
    准备运行环境

    按官方文档确认运行环境(常见为 Node.js 或 Python),装好后再执行安装命令。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
文档检索问答

在你的文档库里按问题找答案。

知识库读写

把新资料写进知识库,随用随取。

内容整理

把零散资料归纳成结构化笔记。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 已适配 Cursor、Codex、Zed,换客户端不用重新研究配置。

先想清楚的地方

  • 没有现成安装命令,需要按官方文档自己填启动命令和参数。
  • 使用前要准备好API Key对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在文档知识场景里让模型直接调用外部能力的人。
  • 已经在用 Cursor、Codex 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Memory Mcp 1file当前 未标注 未标注 未标注 无 未标注
dify 未标注 stdio · 本地进程 本地部署 有 2026-04-11
open-webui 未标注 stdio · 本地进程 本地部署 有 2026-04-11
JeecgBoot 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Cherry Studio 未标注 未标注 未标注 无 2026-05-17
mempalace 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

文档知识
字段来自项目仓库与公开索引,中文说明由本站标注
提供方pomazanbohdan上游标注的维护方 pomazanbohdan
分类文档知识本站按上游分类展示
连接方式未标注上游未给出传输方式
鉴权方式API Key远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Cross-platform本地安装时用到的包标识与运行时
部署类型未标注上游给出的部署形态
最近核验未标注上游最后核验时间

详细介绍

19.2 KB
来自项目仓库与上游目录的原文,未做删改

Please use https://github.com/tenatarika/vex

🧠 Memory MCP Server

A high-performance, pure Rust Model Context Protocol (MCP) server that provides persistent, semantic, and graph-based memory for AI agents.

Works perfectly with:
* Claude Desktop
* Claude Code (CLI)
* Gemini CLI
* OpenAI Codex (CLI / IDE)
* Cursor
* OpenCode
* Cline / Roo Code
* Any other MCP-compliant client.

🏆 The "All-in-One" Advantage

Unlike other memory solutions that require a complex stack (Python + Vector DB + Graph DB), this project is a single, self-contained executable.

  • ✅ No External Database (SurrealDB is embedded)
  • ✅ No API Keys, No Cloud, No Python — Everything runs 100% locally via an embedded ONNX runtime. The embedding model is baked into the binary and runs on CPU. Nothing leaves your machine.
  • ✅ Zero Setup (Just run one Docker container or binary)

It combines:
1. Vector Search (FastEmbed) for semantic similarity.
2. Knowledge Graph (PetGraph) for entity relationships.
3. Code Indexing with symbol graph (calls, extends, implements) for deep codebase understanding.
4. Hybrid Retrieval (Reciprocal Rank Fusion) for best results.

🏗️ Architecture```mermaid

graph TD
User[AI Agent / IDE]

subgraph "Memory MCP Server"
    MS[MCP Server]

    subgraph "Core Engines"
        ES[Embedding Service]
        GS[Graph Service]
        CS[Codebase Service]
    end

    MS -- "Store / Search" --> ES
    MS -- "Relate Entities" --> GS
    MS -- "Index" --> CS

    ES -- "Vectorize Text" --> SDB[(SurrealDB Embedded)]
    GS -- "Knowledge Graph" --> SDB
    CS -- "AST Chunks" --> SDB
end

User -- "MCP Protocol" --> MS

> **Click here for the Detailed Architecture Documentation**

---
## MCP Protocol & Transports

The server uses `rmcp` 3.2 and supports both protocol lifecycles:

* **MCP 2026-07-28 stateless requests:** clients may begin with
  `server/discover`; every request carries the protocol version and client
  metadata in `_meta`. The process stores no MCP session, `Mcp-Session-Id`, or
  mutable `currentProject`.
* **MCP 2025-11-25 compatibility:** clients using the legacy
  `initialize`/`initialized` lifecycle remain supported.

This binary exposes MCP over **stdio**. Run one process per local workspace and
mount that workspace at `/project` when using Docker. Streamable HTTP is not
enabled or advertised by this release, so it introduces no HTTP session
management or shared-server authentication surface. Code indexing receives an
explicit path through `index_project`; code search can be narrowed with
`project_id` when one process contains multiple indexed projects. Roots
negotiation is not used.

---

## 🤖 Agent Integration (System Prompt)

Memory is useless if your agent doesn't check it. To get the "Long-Term Memory" effect, you must instruct your agent to follow a strict protocol.

We provide a battle-tested **Memory Protocol (AGENTS.md)** that you can adapt.

### 🛡️ Core Workflows (Context Protection)

The protocol implements specific flows to handle **Context Window Compaction** and **Session Restarts**:

1.  **🚀 Session Startup**: The agent *must* search for `TASK: in_progress` immediately. This restores the full context of what was happening before the last session ended or the context was compacted.
2.  **⏳ Auto-Continue**: A safety mechanism where the agent presents the found task to the user and waits (or auto-continues), ensuring it doesn't hallucinate a new task.
3.  **🔄 Triple Sync**: Updates **Memory**, **Todo List**, and **Files** simultaneously. If one fails (e.g., context lost), the others serve as backups.
4.  **🧱 Prefix System**: All memories use prefixes (`TASK:`, `DECISION:`, `RESEARCH:`) so semantic search can precisely target the right type of information, reducing noise.

These workflows turn the agent from a "stateless chatbot" into a "stateful worker" that survives restarts and context clearing.

### Recommended System Prompt Snippet

Instead of scattering instructions across IDE-specific files (like `.cursorrules`), establish `AGENTS.md` as the **Single Source of Truth**.

Instruct your agent (in its base system prompt) to:
1.  **Read `AGENTS.md`** at the start of every session.
2.  **Follow the protocols** defined therein.

Here is a minimal reference prompt to bootstrap this behavior:```markdown
# 🧠 Memory & Protocol
You have access to a persistent memory server and a protocol definition file.

1.  **Protocol Adherence**:
    - READ `AGENTS.md` immediately upon starting.
    - Strictly follow the "Session Startup" and "Sync" protocols defined there.

2.  **Context Restoration**:
    - Run `search_text("TASK: in_progress")` to restore context.
    - Do NOT ask the user "what should I do?" if a task is already in progress.

Why this matters?

Without this protocol, the agent loses context after compaction or session restarts. With this protocol, it maintains the full context of the current task, ensuring no steps or details are lost, even when the chat history is cleared.


🔌 Client Configuration

Universal Docker Configuration (Any IDE/CLI)

To use this MCP server with any client (Claude Code, OpenCode, Cline, etc.), use the following Docker command structure.

Key Requirements:
1. Memory Volume: -v mcp-data:/data (Persists your graph, embeddings, and cached model weights)
2. Project Volume: -v $(pwd):/project:ro (Allows the server to read and index your code)
3. Init Process: --init (Ensures the server shuts down cleanly)

> [!TIP]
> One volume persists everything: The single -v mcp-data:/data mount covers both the SurrealDB database and the ~1.2 GB embedding model (stored under /data/models/). There is no need for a separate volume for /data/models — it is already a subdirectory of /data and is preserved automatically. Without a named volume, Docker creates a new anonymous volume on each docker run, causing the model to re-download (~1.2 GB) every time.

JSON Configuration (Claude Desktop, etc.)

Add this to your configuration file (e.g., claude_desktop_config.json):```json
{
"mcpServers": {
"memory": {
"command": "docker",
"args": [
"run",
"--init",
"-i",
"--rm",
"--memory=3g",
"-v", "mcp-data:/data",
"-v", "/absolute/path/to/your/project:/project:ro",
"ghcr.io/pomazanbohdan/memory-mcp-1file:latest"
]
}
}
}


> **Note:** Replace `/absolute/path/to/your/project` with the actual path you want to index. In some environments (like Cursor or VSCode extensions), you might be able to use variables like `${workspaceFolder}`, but absolute paths are most reliable for Docker.

### Cursor (Specific Instructions)

1.  Go to **Cursor Settings** > **Features** > **MCP Servers**.
2.  Click **+ Add New MCP Server**.
3.  **Type**: `stdio`
4.  **Name**: `memory`
5.  **Command**:```bash
    docker run --init -i --rm --memory=3g -v mcp-data:/data -v "/Users/yourname/projects/current:/project:ro" ghcr.io/pomazanbohdan/memory-mcp-1file:latest
    ```
    *(Remember to update the project path when switching workspaces if you need code indexing)*

### OpenCode / CLI```bash
docker run --init -i --rm --memory=3g \
  -v mcp-data:/data \
  -v $(pwd):/project:ro \
  ghcr.io/pomazanbohdan/memory-mcp-1file:latest

NPX / Bunx (No Docker required)

You can run the server directly via npx or bunx. The npm package automatically downloads the correct pre-compiled binary for your platform.

Claude Desktop

Add to claude_desktop_config.json:```json
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["-y", "memory-mcp-1file"]
}
}
}


#### Claude Code (CLI)```bash
claude mcp add memory -- npx -y memory-mcp-1file

Cursor

  1. Go to Cursor Settings > Features > MCP Servers.
  2. Click + Add New MCP Server.
  3. Type: command
  4. Name: memory
  5. Command: npx -y memory-mcp-1file

Or add to .cursor/mcp.json:```json
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["-y", "memory-mcp-1file"]
}
}
}


#### Windsurf / VS Code

Add to your MCP settings:```json
{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "memory-mcp-1file"]
    }
  }
}

Bun```json

{
"mcpServers": {
"memory": {
"command": "bunx",
"args": ["memory-mcp-1file"]
}
}
}


#### OpenAI Codex CLI (project-scoped)
This repository includes a trusted-project `.codex/config.toml` that starts
`memory-mcp-1file@0.9.2` over local STDIO, stores data in `.codex/data`, and
exposes a 16-tool project allowlist. The destructive tools
`delete_memory`, `delete_project`, and `reset_all_memory` are intentionally
excluded from the project configuration. Native Codex indexing is constrained
to the current repository by `MEMORY_MCP_ALLOWED_INDEX_ROOT`.

Project-scoped Codex configuration is loaded only after you explicitly trust
the repository. On Windows, verify the package independently first:```powershell
npx -y memory-mcp-1file@0.9.2 -- --help

Then run codex from the repository and verify the server with:```text
/mcp


or:```bash
codex mcp list
codex mcp get memory

The required = true setting makes a failed Memory MCP startup visible instead
of silently running the project without its memory workflow.
The tool allowlist controls which MCP tools Codex loads; it is not a process
sandbox. Trust the repository and npm package before enabling this configuration.

> Note: Unlike Docker, npx/bunx runs the binary locally — it already has access to your filesystem, so no directory mounting is needed. To customize the data storage path, pass --data-dir via args:
>json > "args": ["-y", "memory-mcp-1file", "--", "--data-dir", "/path/to/data"] >

Gemini CLI

Add to your ~/.gemini/settings.json:```json
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["-y", "memory-mcp-1file"]
}
}
}


Or with Docker:```json
{
  "mcpServers": {
    "memory": {
      "command": "docker",
      "args": [
        "run", "--init", "-i", "--rm", "--memory=3g",
        "-v", "mcp-data:/data",
        "-v", "${workspaceFolder}:/project:ro",
        "ghcr.io/pomazanbohdan/memory-mcp-1file:latest"
      ]
    }
  }
}

✨ Key Features

  • Semantic Memory: Stores text with vector embeddings (granite by default) for "vibe-based" retrieval.
  • Graph Memory: Tracks entities (User, Project, Tech) and their relations (uses, likes). Supports PageRank-based traversal.
  • Code Intelligence: Indexes local project directories (AST-based chunking) for Rust, Python, TypeScript, JavaScript, Go, Java, and Dart/Flutter. Tracks calls, imports, extends, implements, and mixin relationships between symbols.
  • Temporal Validity: Memories can have valid_from and valid_until dates.
  • SurrealDB Backend: Fast, embedded, single-file database.

🛠️ Tools Available

The server exposes 19 tools to the AI model, organized into logical categories.

🧠 Core Memory Management

Tool Description
store_memory Store a new memory with content and optional metadata.
update_memory Update memory fields.
delete_memory Delete memory by ID.
list_memories List memories (newest first).
get_memory Get full memory by ID.
invalidate Soft-delete memory, optionally linking replacement.
get_valid Get valid memories. Optional timestamp (ISO 8601) for point-in-time query.

🔎 Search & Retrieval

Tool Description
recall Hybrid search (Vector + Keyword + Graph via RRF). Default for memories.
search_memory Search memories. mode: vector (default) or bm25.

🕸️ Knowledge Graph

Tool · Description
knowledge_graph · Unified KG operations. action: create_entity \ · create_relation \ · get_related \ · detect_communities.

💻 Codebase Intelligence

Tool · Description
index_project · Index codebase directory for code search.
delete_project · Delete indexed project.
recall_code · Code retrieval. mode: vector or hybrid (default). Hybrid uses vector+BM25+graph fusion.
search_symbols · Search code symbols by name.
symbol_graph · Navigate symbol graph. action: callers \ · callees \ · related.
project_info · Project info. action: list \ · status \ · stats.

⚙️ System & Maintenance

Tool Description
get_status Get system status and startup progress.
reset_all_memory DANGER: Reset all database data (requires confirm=true).
how_to_use Show tool usage examples and parameter combinations.

⚙️ Configuration

Environment variables or CLI args:

Arg Env Default Description
--data-dir DATA_DIR ./data DB location
--model EMBEDDING_MODEL granite Embedding model (granite, e5_multi, qwen3, gemma, bge_m3, nomic, e5_small)
--mrl-dim MRL_DIM (native) Output dimension for MRL-supported models (e.g. 64, 128, 256, 512, 1024 for Qwen3). Defaults to the model's native maximum dimension (384 for Granite, 1024 for Qwen3).
--batch-size BATCH_SIZE 8 Maximum batch size for embedding inference
--cache-size CACHE_SIZE 1000 LRU cache capacity for embeddings
--timeout TIMEOUT_MS 30000 Timeout in milliseconds
--idle-timeout IDLE_TIMEOUT 0 Idle timeout in minutes. 0 = disabled
--log-level LOG_LEVEL info Verbosity
(None) HF_TOKEN (None) HuggingFace Token (ONLY required for gated models like gemma)
(None) EMBEDDING_QUEUE_CAPACITY 256 Max size of the background embedding queue
(None) EMBEDDING_BATCH_SIZE 8 How many files to process in one embedding chunk
(None) INDEX_BATCH_SIZE 20 How many files to process in one incremental chunk
(None) INDEX_DEBOUNCE_MS 2000 MS to wait before flushing index events (debounce)
(None) MANIFEST_DIFF_INTERVAL_MINS 10 Minutes between periodic missing file checks

🧠 Available Models

You can switch the embedding model using the --model arg or EMBEDDING_MODEL env var.

When neither option is provided, the binary uses Granite. Configuration precedence is:
explicit --model argument, then EMBEDDING_MODEL, then the built-in Granite default.

Argument Value HuggingFace Repo Dimensions Size Use Case
granite ibm-granite/granite-embedding-97m-multilingual-r2 384 ~195 MB Default. Multilingual and code retrieval with ModernBERT and CLS pooling.
e5_multi intfloat/multilingual-e5-base 768 1.1 GB Legacy multilingual model, good balance of quality and performance.
qwen3 Qwen/Qwen3-Embedding-0.6B 1024 (MRL) 1.2 GB Top open-source 2026 model, 32K context, MRL support.
gemma onnx-community/embeddinggemma-300m-ONNX 768 (MRL) ~195 MB Lighter alternative with MRL support. (Requires proprietary license agreement)
bge_m3 BAAI/bge-m3 1024 2.3 GB State-of-the-art multilingual hybrid retrieval. Heavy.
nomic nomic-ai/nomic-embed-text-v1.5 768 1.9 GB High quality long-context BERT-compatible.
e5_small intfloat/multilingual-e5-small 384 134 MB Fastest, minimal RAM. Good for dev/testing.

granite produces native 384-dimensional, L2-normalized CLS embeddings. The current Candle CPU path caps inputs at 512 tokens to bound the quadratic attention memory cost; the model itself supports up to 32K tokens.

📉 Matryoshka Representation Learning (MRL)

Models marked with (MRL) support dynamically truncating the output embedding vector to a smaller dimension (e.g., 512, 256, 128) with minimal loss of accuracy. This saves database storage and speeds up vector search.

Use the --mrl-dim argument to specify the desired size. If omitted, the default is the model's native base dimension (e.g., 1024 for Qwen3).

Warning: Once your database is created with a specific dimension, you cannot change it without wiping the data directory.

🔒 Gated Models & Authentication (Gemma)

By default, the server uses Granite, an Apache 2.0 model that downloads automatically without any authentication.

However, if you choose to use Gemma (--model gemma), you must authenticate because it is a "Gated Model" with a proprietary license.

To use Gemma:
1. Go to google/embeddinggemma-300m on Hugging Face.
2. Log in and click "Agree to access repository".
3. Generate an Access Token at HF Tokens (Read access is enough).
4. Start the server with the token:```bash

Using environment variable

HF_TOKEN="hf_your_token_here" memory-mcp --model gemma

Or via .env file (see .env.example)

```

> [!WARNING]
> Changing Models & Data Compatibility
>
> Fresh installations use granite (384 dimensions) by default. Existing data directories created with e5_multi (768 dimensions) remain usable only when starting explicitly with --model e5_multi.
>
> Switching to a model with different dimensions requires a new data directory (or wiped volume) and a full re-index.
>
> Even switching between models with the same dimensions (e.g., e5_multi <-> nomic) is not recommended because their semantic spaces differ.

🔮 Future Roadmap (Research & Ideas)

Based on analysis of advanced memory systems like Hindsight (see their documentation for details on these mechanisms), we are exploring these "Cognitive Architecture" features for future releases:

1. Meta-Cognitive Reflection (Consolidation)

  • Problem: Raw memories accumulate noise over time (e.g., 10 separate memories about fixing the same bug).
  • Solution: Implement a reflect background process (or tool) that periodicallly scans recent memories to:
    • De-duplicate redundant entries.
    • Resolve conflicts (if two memories contradict, keep the newer one or flag for review).
    • Synthesize low-level facts into high-level "Insights" (e.g., "User prefers Rust over Python" derived from 5 code choices).

2. Temporal Decay & "Presence"

  • Problem: Old memories can sometimes drown out current context in semantic search.
  • Solution: Integrate Time Decay into the Reciprocal Rank Fusion (RRF) algorithm.
    • Give a calculated boost to recent memories for queries implying "current state".
    • Allow the agent to prioritize "working memory" over "historical archives" dynamically.

3. Namespaced Memory Banks

  • Current boundary: Code indexes already support explicit project_id
    filtering, while memory records remain process-wide.
  • Future work: Extend namespace/project scoping to memory and graph
    operations so one shared server can isolate multiple agent workspaces.

4. Epistemic Confidence Scoring

  • Problem: The agent treats a guess the same as a verified fact.
  • Solution: Add a confidence score (0.0 - 1.0) to memory schemas.
    • Allows storing hypotheses ("I think the bug is in auth.rs", confidence: 0.3).
    • Retrieval tools can filter out low-confidence memories when answering factual questions.

License

MIT

常见问题

7 问
答案由本站依据条目字段整理,不引用上游原文
Memory Mcp 1file 怎么安装?

资料没有给出安装命令,请到官方仓库或文档按说明接入;这类条目多数是生态应用,或尚未发布可安装包。

Memory Mcp 1file 怎么在 Cursor、Codex、Zed 里配置?

它的传输方式未标注,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Memory Mcp 1file 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Memory Mcp 1file 需要 API Key 吗?

资料标注需要API Key认证,使用前准备好对应凭据,并按最小权限配置。

Memory Mcp 1file 支持哪些客户端?

资料标注支持 Cursor、Codex、Zed;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Memory Mcp 1file 能提供哪些能力?

资料显示能力标签包括 vector search、knowledge graph、code indexing。具体工具清单以官方文档为准。

Memory Mcp 1file 需要什么运行环境?

运行时为 Cross-platform。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 未标注。