cortex-local-memory
Supports Baidu as an embedding provider for Chinese-language vector search and hybrid retrieval.
Provides a built-in Grafana dashboard for visualizing Cortex's Prometheus metrics.
Supports Ollama as a local embedding provider, allowing Cortex to generate embeddings through an Ollama server for hybrid retrieval.
Supports OpenAI as an embedding provider for generating vector embeddings used in hybrid search.
Exposes Prometheus metrics on a dedicated endpoint for monitoring and observability.
🎬 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 全部 + |
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, |
中文笔记搜不准("机器学习"搜不到"机器学习模型") | 通用分词器 | 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/liveWeb 控制台(
/admin,默认仅本机)
🔌 MCP Tools
Cortex 向 AI Agent 暴露 14 个 MCP 工具:
工具 | 作用 |
| 混合检索知识库,返回带路径与标题的结果 |
| 构建 RAG 上下文(适合直接塞进 prompt) |
| 查询补全建议 |
| 写入一条记忆 |
| 批量写入记忆 |
| 检索记忆 |
| 删除指定记忆 |
| 批量删除记忆 |
| 按函数/类名精确检索代码符号(Go 用官方 AST) |
| 知识库统计 |
| 健康检查 |
| 知识库主题地图 |
| 基于知识库内容生成执行计划 |
| 项目级上下文聚合 |
手动接入(如果 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 ~/notesDocker
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 个:
命令 | 用途 |
| 索引文档(实时进度、断点续传、并发 8–16 worker) |
| 一键启动 MCP + REST + 自动注册 AI 工具 |
| 命令行检索 |
| 监听目录,增量索引 |
| 查看文档数、分块数、用量 |
其他: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'类别 | 端点 |
检索 |
|
文档 |
|
记忆 |
|
MCP |
|
认证 |
|
健康 |
|
监控 |
|
管理 |
|
默认只返回 800 字符摘要。需要全文传
?full=1(响应体会从 5.8 KB 涨到 ~1.9 MB)。
角色权限(RBAC)
开启 auth_enabled: true 后:
角色 | 读 | 写 | 管理用户/密钥 |
| ✅ | ❌ | ❌ |
| ✅ | ✅ | ❌ |
| ✅ | ✅ | ✅ |
cortex user add alice --role admin --password '...'
cortex user set-role bob viewer📦 支持格式(25 种)
类别 | 格式 |
文档 |
|
代码 |
|
配置 |
|
代码符号: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 控制台( | ✅ 可用 |
关于付费版:目前没有可购买的付费版。
说清楚以免误导: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。
🧪 质量
项 | 状态 |
| 0 警告 |
| 24/24 包通过 |
跨平台构建 | 6/6(linux/darwin/windows × amd64/arm64) |
安装验证 | Windows + Linux 实跑官方安装命令 |
基准可复现 |
|
回归测试覆盖真实事故:索引统计丢失 · 符号表列名 · 登录 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 toolscortex_code_searchA
Search code with file:line results. Filters by language or path, useful for locating a function or symbol definition.
Inputs: query (required), top_k, language, path_like, +1 more.
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_searchC
Search memory entries in the cortex knowledge base
Inputs: query (required), top_k.
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_searchB
Search the local knowledge base (cortex) using vector and fts and return relevant chunks
Inputs: query (required), 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
Scored across 14 tools
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.
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.
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.
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
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Hosted MCP memory for coding agents: persistent across sessions, editable markdown, team sharing.
Graph-native persistent memory for AI agents — 33 MCP tools, zero-LLM writes.
Self-hosted AI workspace: semantic RAG document search, long-term memory, and AI chat via MCP.
Related MCP Servers
- AlicenseBqualityCmaintenancePersistent 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.1023MIT
- AlicenseAqualityFmaintenanceLocal-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.7109 npm4MIT
- AlicenseAqualityAmaintenancePersistent 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.5491MIT
- AlicenseAqualityBmaintenanceLocal-first memory layer for AI coding agents — Markdown as source of truth, MCP server + CLI, human-reviewed capture, team knowledge via git PRs613779 npm6Apache 2.0