Skip to main content
Glama
cortex-local-memory

cortex-local-memory


🎬 30 秒看到效果

# 1. 安装(一条命令,不需要 Go / Node / Docker)
curl -fsSL https://cortex.qataroasis.cc/install.sh | sh          # macOS / Linux
# Windows PowerShell:irm https://cortex.qataroasis.cc/install.ps1 | iex

# 2. 索引你的知识库
cortex index ~/notes ~/Documents

# 3. 启动并自动接入你的 AI 工具
cortex start

想先要 Pro 的额度(50 万篇 / 100 GB)?领 14 天试用,不用付款,到期自动降回 Free,索引不丢。

cortex start 会做三件事:

  • 启动 MCP 服务器(stdio)+ REST API

  • 自动写入你的 AI 工具配置(Claude Code / Cursor / OpenCode / Trae),带备份,不覆盖已有 MCP server

  • 打印接入指引

然后回到 Claude Code,直接问:

「我之前写在笔记里关于 Redis 缓存穿透的那段怎么处理的?」

Claude 会通过 Cortex 的 MCP 工具检索你的笔记,而不是猜。


Related MCP server: tdai-memory-mcp

Pricing

Free 永久免费,功能不阉割,只限制文档数量。需要省时间的能力再买 Pro。

方案

价格

包含

Free

¥0 / $0

核心全功能:MCP 工具、向量+BM25 混合检索、三层去重、REST API、CLI、中文分词、Web Admin、记忆系统。上限 5,000 篇文档 / 1 GB

Pro

¥199 一次性 / $29

Free 全部 + console(Web 控制台)、rerank(重排提升召回精度)、auto-index(文件变更自动索引)。额度提升到 50 万篇 / 100 GB。离线签名 License,永久有效,含 1 年更新

Team / Enterprise

预约洽谈

审计日志已交付;RBAC、SSO/OIDC、S3 备份、私有化 SLA 仍在开发中,交付前不标价

价格仅以上表为准。购买或咨询请在 issue 标题标注 [pricing],我会直接回复。

直接购买 Pro:https://cortex.qataroasis.cc —— PayPal 付款 $29,24 小时内收到 License。文档与下载见 cortex.qataroasis.cc。

Pro 版基于闭源企业版 cortex-ee 交付,License 通过 Ed25519 离线签名验证,不联网、不上报、不采集任何使用数据。


💡 Why Cortex

你可能正在遇到的问题

你的痛点

现有方案

Cortex 的做法

AI 聊完就忘,每次都要重新粘贴上下文

手动复制粘贴

持久化记忆层,MCP 工具让 Agent 主动检索

想把 2 万个笔记接进 Cursor,结果要装 Docker、跑向量库、配 5 个服务

Dify / RAGFlow / AnythingLLM

单文件 33–36 MB,cortex start 一条命令

中文笔记搜不准("机器学习"搜不到"机器学习模型")

通用分词器

CJK 专用分词,标题与正文分别处理

数据必须留在本地(客户资料、代码、病历)

云端 RAG 服务

100% 本地,只有你配的 embedding API 会出网

云端按量计费,团队 10 个人每月几百刀

托管服务

Apache-2.0 免费,自建零边际成本

和同类工具的区别

Cortex

AnythingLLM

Dify

Chroma / Qdrant

部署

单二进制 + SQLite

Docker / Desktop

Docker Compose 多服务

需自建检索服务

安装到可用

~1 分钟

~5 分钟

~15 分钟

~30 分钟

中文分词

✅ CJK 专用

通用

通用

无(只管向量)

国内 embedding

✅ 通义 / 智谱 / 文心

❌

部分

❌

MCP 原生

✅ 14 个工具 + 自动注册

✅

插件式

❌

Agent 记忆

✅ 独立记忆 API

会话级

会话级

❌

许可

Apache-2.0

MIT

Apache-2.0 + 附加条款

Apache-2.0

诚实说明:Cortex 支持 25 种格式,比 XERJ(40+)少;没有 Elasticsearch 兼容 DSL; 英文长尾查询比中文慢。这些是真实短板,不是谦虚。


📊 Performance: measured, not estimated

全部可由 cmd/cortex-bench 复现。环境:Windows 11 / x86_64 / 本地 SSD / CGO_ENABLED=0 / FTS-only。

检索延迟(27,157 文档 / 84,562 分块的真实知识库)

指标

实测值

P50

0.43 ms

P95

2.35 ms

P99

3.91 ms

吞吐(单实例)

1,440 QPS

响应体(10 条结果)

5.8 KB

冷启动

0.36 s

常驻内存

53 MB

索引吞吐(合成语料,可复现)

语料规模

吞吐

分块数

1,000 文档

328 files/s

2,510

5,000 文档

365 files/s

12,668

检索质量

指标

1,000 文档

5,000 文档

Recall@1

1.000

1.000

Recall@5

1.000

1.000

Recall@10

1.000

1.000

MRR

1.000

1.000

关于这些数字的边界(请务必阅读):

  • 合成语料的 recall 证明的是「检索管线正确、无系统性漏召」,不代表语义检索质量(真实质量需要 embedding + 重排)。

  • Windows 计时器分辨率是 507µs,亚毫秒延迟无法精确测量,P50 标注为实测下限。

  • 索引吞吐语料与 XERJ 不同(XERJ 含二进制解析、支持 40+ 格式),不能直接横比。

完整报告:性能优化记录 · 基准方法与边界


✨ 核心能力

🔍 混合检索

  • FTS5 BM25(SQLite 原生全量索引)

  • 向量检索 + RRF 融合排序

  • CJK 分词:标题与正文分别处理

  • 两級缓存(内存 L1 + SQLite L2,异步写入)

🧠 Agent 记忆

  • /v1/memory 写入与批量写入

  • 记忆检索与 RAG 上下文构建

  • 分块去重(MinHash)

🔌 MCP 原生

  • 14 个工具,stdio + Streamable HTTP (SSE)

  • 自动注册 Claude Code / Cursor / OpenCode / Trae

  • 写入前备份,保留你已有的 MCP server

  • 无配置即用

📦 单二进制

  • 33–36 MB,6 平台(linux/darwin/windows × amd64/arm64)

  • 纯 Go,无 CGO,无外部数据库

  • SQLite + 向量索引内嵌

  • Windows / macOS / Linux 同等支持

🔐 企业级基础设施

  • RBAC:admin / editor / viewer 三角色

  • Ed25519 离线许可(feature 门控)

  • 配额强制(文档数 / 存储)

  • 审计日志(企业版)

📈 可观测

  • 32 个 Prometheus 指标

  • 内置 Grafana 面板

  • /health /health/ready /health/live

  • Web 控制台(/admin,默认仅本机)


🔌 MCP Tools

Cortex 向 AI Agent 暴露 14 个 MCP 工具:

工具

作用

cortex_search

混合检索知识库,返回带路径与标题的结果

cortex_context

构建 RAG 上下文(适合直接塞进 prompt)

cortex_suggest

查询补全建议

cortex_memory_write

写入一条记忆

cortex_memory_batch

批量写入记忆

cortex_memory_search

检索记忆

cortex_memory_delete

删除指定记忆

cortex_memory_delete_batch

批量删除记忆

cortex_code_search

按函数/类名精确检索代码符号(Go 用官方 AST)

cortex_stats

知识库统计

cortex_health

健康检查

cortex_map

知识库主题地图

cortex_plan

基于知识库内容生成执行计划

cortex_project_context

项目级上下文聚合

手动接入(如果 cortex start 没覆盖你的工具):

{
  "mcpServers": {
    "cortex": {
      "command": "cortex",
      "args": ["mcp"]
    }
  }
}

🛠️ 安装

一行安装(推荐,无需 Go)

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/lh123aa/cortex/master/scripts/install.sh | sh

# Windows PowerShell
irm https://raw.githubusercontent.com/lh123aa/cortex/master/scripts/install.ps1 | iex

安装脚本会:下载对应平台预编译二进制 → 校验 SHA256 → 安装到 PATH → 运行 cortex install。

指定版本:

CORTEX_VERSION=v4.0.1 sh scripts/install.sh

从源码构建(需要 Go 1.25+)

git clone https://github.com/lh123aa/cortex.git
cd cortex
CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o cortex ./cmd/cortex
./cortex install ~/notes

Docker

docker build -t cortex .

# 索引(挂载你的文档目录与数据目录)
docker run --rm -v ~/notes:/data -v ~/.cortex:/root/.cortex \
  cortex index /data

# 启动 REST API(cortex serve 默认端口 2021,需显式映射)
docker run -d --name cortex \
  -p 2021:2021 -p 9090:9090 \
  -v ~/.cortex:/root/.cortex \
  cortex serve -p 2021

⚠️ 官方 Dockerfile 的 EXPOSE 写的是 8080/9090,而 cortex serve 默认监听 2021。 以上命令用 -p 2021:2021 并显式传 -p 2021 是一致的做法。


⚡ CLI

17 个命令,核心 5 个:

命令

用途

cortex index <path>

索引文档(实时进度、断点续传、并发 8–16 worker)

cortex start

一键启动 MCP + REST + 自动注册 AI 工具

cortex search <query>

命令行检索

cortex watch <path>

监听目录,增量索引

cortex status

查看文档数、分块数、用量

其他:install serve mcp setup context dedup usage user license version。


📡 API

19 个 REST 端点。核心:

# 检索
curl 'http://localhost:2021/v1/search?q=Redis%20缓存穿透&limit=5'

# 写入记忆
curl -X POST http://localhost:2021/v1/memory \
  -H 'Content-Type: application/json' \
  -d '{"content":"今天解决了缓存穿透问题,用布隆过滤器"}'

# RAG 上下文
curl 'http://localhost:2021/v1/context?q=缓存方案&limit=5'

类别

端点

检索

GET /v1/search GET /v1/context GET /v1/suggest

文档

GET /v1/docs GET /v1/docs/:id GET /v1/stats

记忆

POST /v1/memory POST /v1/memory/batch GET /v1/memory/search GET /v1/memory/context DELETE /v1/memory/:id

MCP

/mcp(Streamable HTTP + SSE)

认证

POST /auth/register POST /auth/login POST /auth/logout

健康

GET /health GET /health/ready GET /health/live

监控

GET :9090/metrics(独立端口,32 个 Prometheus 指标)

管理

GET /admin(Web 控制台,默认仅本机)GET /admin/keys(仅 admin 角色)

默认只返回 800 字符摘要。需要全文传 ?full=1(响应体会从 5.8 KB 涨到 ~1.9 MB)。

角色权限(RBAC)

开启 auth_enabled: true 后:

角色

读

写

管理用户/密钥

viewer

✅

❌

❌

editor

✅

✅

❌

admin

✅

✅

✅

cortex user add alice --role admin --password '...'
cortex user set-role bob viewer

📦 支持格式(25 种)

类别

格式

文档

.md .pdf .docx .txt

代码

.go .py .js .ts .java .cpp .c .rb .sh .ps1 .css .html

配置

.yaml .json .toml .ini .cfg .hcl .env .properties .xml

代码符号:Go 使用官方 go/ast 解析器(精确);其他语言使用词法提取。


🔧 配置

# ~/.cortex/config.yaml
cortex:
  db_path: ~/.cortex/cortex.db
  log_level: info
  auth_enabled: false

embedding:
  provider: none            # none | ollama | openai | cohere | voyage | dashscope | zhipu | baidu
  ollama:
    base_url: http://localhost:11434
    model: nomic-embed-text
  openai:
    api_key: ""

index:
  workers: 8                # 并发索引 worker
  max_tokens: 512           # 单块最大 token
  overlap_tokens: 64        # 块间重叠
  min_chars: 50             # 低于此字符数的文档会被跳过

search:
  cache_ttl: 5m
  default_top_k: 10
  prefetch: false           # 预联想(消耗额外内存)

Embedding 提供商(7 家 + 零依赖模式)

none(纯 FTS,零依赖,默认)| ollama(本地,推荐)| openai | cohere | voyage | dashscope(阿里通义)| zhipu(智谱)| baidu(百度文心)

内置常用模型预设:nomic-embed-text、bge-m3、text-embedding-3-small/large、embed-multilingual-v3.0、voyage-3 等。

cortex setup    # 交互式配置向导

🏗️ 架构

┌─────────────────────────────────────────────────┐
│  Claude Code · Cursor · OpenCode · Trae          │
└──────────────┬──────────────────────────────────┘
               │ MCP (stdio / Streamable HTTP)
┌──────────────▼──────────────────────────────────┐
│              Cortex (单二进制)                    │
│ ┌────────────┬────────────┬───────────────────┐ │
│ │ MCP Server │ REST API   │ Web Console       │ │
│ │ 14 tools   │ 19 routes  │ /admin            │ │
│ └─────┬──────┴─────┬──────┴────────┬──────────┘ │
│       │            │               │            │
│ ┌─────▼────────────▼───────────────▼──────────┐ │
│ │ Hybrid Search: FTS5 BM25 + Vector + RRF     │ │
│ └─────┬───────────────────────────────────────┘ │
│ ┌─────▼───────────────────────────────────────┐ │
│ │ SQLite (文档/分块/FTS/向量/符号/缓存/用户)   │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘

设计取舍:

  • SQLite 而非独立向量库 —— 目标是「下载即用」,免运维。规模上限约 3 万文档。

  • 单二进制而非容器编排 —— 个人/小团队的真实使用场景是笔记本,不是 K8s。

  • FTS-only 默认 —— 零依赖启动;需要语义检索时装 Ollama 开 embedding。


🔐 开源与商业

开源版(Apache-2.0)功能完整可用,无功能阉割。

能力

开源版现状

索引 / 混合检索 / MCP 14 工具 / REST API / CLI

✅ 可用

中文化检索(CJK 分词)

✅ 可用

Agent 记忆 API

✅ 可用

RBAC(admin / editor / viewer)

✅ 可用

离线许可机制(Ed25519 签发与激活)

✅ 可用

文档配额强制

✅ 可用(Free:5,000 篇 / 1 GB)

Web 控制台(/admin,默认仅本机)

✅ 可用

关于付费版:目前没有可购买的付费版。

说清楚以免误导:Ed25519 离线许可与配额门控的机制已经完整可用,但 审计日志、SSO / OIDC、S3 备份、多租户 等企业能力尚未实现, pkg/ext 扩展接口目前是空的。这些能力列在路线图上,不是现有功能。

需要私有化部署支持?

如果你的场景要求数据不出内网、需要中文检索、又不想维护 Docker / 向量库编排, Cortex 的单二进制形态正好合适。可以提供远程部署与定制支持(按次/按单计费的服务, 不是软件订阅——软件本身永远开源免费)。

怎么发起: 开一个 部署咨询 Issue, 表单会问你 5 个问题(文档量、格式、环境、使用者、期望查询)。一般 24 小时内回第一句。

能做什么: 远程部署跑通、全量索引、检索效果调优、MCP / HTTP API 接入联调、一次使用培训。 不能做什么(如实说明): 审计日志、SSO / OIDC、S3 备份、多租户这些能力代码里还没有, 不会在报价单上出现;也不做客户数据托管或 7×24 SLA 承诺。

服务按次/按单计价(部署 ¥500 起,私有化部署 + 调优 ¥3,000 起),具体以 Issue 沟通后的报价单为准。

许可迁移记录见 LICENSE_MIGRATION.md。 路线图见 docs/planning/PRODUCT_ITERATION_AND_MONETIZATION_PLAN.md。


🧪 质量

项

状态

go vet ./...

0 警告

go test ./...

24/24 包通过

跨平台构建

6/6(linux/darwin/windows × amd64/arm64)

安装验证

Windows + Linux 实跑官方安装命令

基准可复现

go run ./cmd/cortex-bench all --docs 5000

回归测试覆盖真实事故:索引统计丢失 · 符号表列名 · 登录 token 失效 · RBAC 权限矩阵


❓ FAQ

Q:和 XERJ 什么关系? 同一需求、不同层级。XERJ 是引擎(ES 兼容、40+ 格式),Cortex 是产品(中文优先、单二进制、MCP 开箱即用)。我们索引吞吐已超过它的公开数据,但格式支持仍是短板。

Q:能索引多少文档? 舒适区约 3 万文档。5,000 文档实测 P95 6 ms,27,157 文档 P95 2.35 ms。

Q:数据会上传吗? 不会。默认全本地。只有你主动配置的 embedding API 会出网(可以用 Ollama 完全离线)。

Q:为什么不用 PostgreSQL + pgvector? 目标是「下载即用」。SQLite 免运维,单人/小团队够用。百万级是 v5 的话题。

Q:中文搜索怎么做的? CJK 单字分词 + 标题/正文分别处理 + 查询时 2-gram 展开。解决了「机器学习」搜不到「机器学习模型」的问题。

Q:支持 Windows 吗? 支持,Windows 是主力测试平台之一,有 PowerShell 一键脚本。


🤝 贡献

欢迎 Issue、PR、文档修正。见 CONTRIBUTING.md。

Apache-2.0 下提交即按同许可授权(DCO)。企业版相关目录需要 CLA。


📄 许可证

Apache License 2.0 —— 可自由使用、修改、分发、商用(含闭源产品),保留 NOTICE 即可。

Apache-2.0 不授予商标权:「Cortex」名称与 Logo 需单独授权用于商业产品名。


Available Tools

14 tools
cortex_contextC

Assemble relevant information within a specific token budget limit strictly

Inputs: query (required), token_budget.

cortex_healthA

Check if the cortex server is healthy and responsive. Returns system status, document count, and uptime.

cortex_mapA

Get a map of the local knowledge base: document count, file type breakdown and sample paths. Use this first when you do not know what is indexed.

Inputs: limit.

cortex_memory_batchA

Write multiple memory entries in a single call (max 50), for storing a batch of facts at the end of a session.

Inputs: items (required).

cortex_memory_deleteC

Delete a memory entry from the cortex knowledge base by its ID

Inputs: id (required).

cortex_memory_delete_batchB

Delete multiple memory entries from the cortex knowledge base by their IDs

Inputs: ids (required).

cortex_memory_writeB

Write a memory entry to the cortex knowledge base for persistent storage

Inputs: content (required), tags, source, summary.

cortex_planA

Given a question or task, return a concrete retrieval plan (which queries to run, which mode, what to look for). Does not itself search.

Inputs: question (required).

cortex_project_contextA

Collect context scoped to a project directory: matching documents, chunks and file entry points under that path.

Inputs: path (required), query, top_k.

cortex_statsB

Return Cortex statistics: documents, chunks, vectors, storage usage, current plan and its limits.

Inputs: verbose.

cortex_suggestB

Get smart search suggestions based on partial query and current context. Returns instant results from prefetched cache or fast search.

Inputs: query (required), top_k, current_file.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 14 tools

    Disambiguation4/5

    Search tools are cleanly separated by target: cortex_search (knowledge base), cortex_memory_search (memories), and cortex_code_search (code with file:line). The main overlap is among the three overview/status tools — cortex_health, cortex_stats, and cortex_map all return counts and status information — and between cortex_context and cortex_project_context, though the descriptions differentiate them well enough.

    Naming Consistency4/5

    All 14 tools share a uniform cortex_ prefix and snake_case, with a coherent cortex_memory_* family covering write/batch/write/delete/delete_batch/search. The only deviation is that top-level tools use single nouns (map, plan, stats, health) while the memory family uses resource_verb, but the grouping is predictable rather than chaotic.

    Tool Count5/5

    14 tools sit comfortably in the well-scoped range and each one serves a distinct retrieval, memory-management, or introspection function. No tool looks redundant filler; the memory batch/delete_batch variants correspond to real bulk needs.

    Completeness4/5

    Memory operations cover write, batch write, search, delete, and batch delete, and the knowledge base side covers search, code search, planning, context assembly, and introspection. However, there is no memory update/edit or direct get-by-id/list operation, so retrieving a specific known memory relies entirely on search, and no tool apparently indexes documents, implying ingestion happens elsewhere.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Persistent memory engine for AI coding agents. Single Go binary, zero runtime dependencies, MCP-native. Stores, searches, and deduplicates memories across sessions using embedded SQLite with hybrid FTS + semantic search, memory decay, relation graph, and token-budget context assembly.
      10
      23
      MIT
    • A
      license
      A
      quality
      F
      maintenance
      Local-first MCP memory server that gives AI coding agents long-term memory via SQLite and sqlite-vec, with optional LLM-powered layering. No gateway or API key required.
      7
      109 npm
      4
      MIT
    • A
      license
      A
      quality
      A
      maintenance
      Persistent memory for AI agents as a single Go binary: hybrid recall, self-building knowledge graph, and a live TUI dashboard. Zero infra, offline-first — works with Claude Code, Cursor, Codex, OpenCode, and any MCP client.
      5
      491
      MIT