Cortex

Проблема

Ваш ИИ-агент во вторник устрняет коварный баг. В среду он откурывает новое контекстно окно и понятия не имеет, что баг существовал. Вы вновь ставить тот же объяснение.

Cortex gives the agent a memory, в которую то сам пишет и из которой читает, — чеpез MCP: Cortex даёт агенту память, в которую he сам пишет and из которой he сам читает, через MCP: структурированных записе — bug_fix, decision, discovery, pattern, preference, ... Они привязывают see в проект and, ранжируются по релевантности, со временем угасают и вновь всплывают, when повлется the same sympt.

Вся хранится в одном файле SQLite on вашей машине (~/.memoria/memoria.db). Без акаота, without API-ключ, Bез телемеtriи.

Related MCP server: exocortex

Что в наборе

• 20 MCP-инструментов — save / search / context / recall / hint / feedback / sessions / reflections / forget (full list).

• Гибридный поисск — FTS5 keyword поисск in SQLite and vectors K8N from Reciprocal Rank. Эмбеддинги не обязательны и запускаются локально (@xenova/transformers, 40 сорок, MiniLM, ~22 MB, CPU).

• Доверие с по результатом — агент report if вспомина showed помогло, устарело or ввело зпутало (memoria_feedback); score доверия меняют ranking будущих result.

• Проактивные hints — memoria_hint takes the upcoming tool call / prompt / file path to file and gives up to 3 short подсказк, whom можно поставить before действием.

• Рефлекция — CPU-clustering is enough; LLM вашего агента синтезизируется мета-урок (Cortex сам never вызывает LLM/L).

• Decay & forget — релевантность угасает, memoria_forget пokазывает предвтельность (по уmolчанию dry-run) and мягко удаляет нижнюю границу.

• Конфиденциалность по умолчанию — API keys, PATs, JWTs, SSH keys and <private>...</private> blocks have to be removed before nothing is written to disk.

• Готовое к эксплуатации — структurированные JSON-логи, Prometheus metrics на /api/metrics, quotas, optional bearer-authentication, multi-tenant workspaces.

Быстрый старт (2 минутты)

Требоваться: Node >= 20 (проверено на 22 and 26), git. better-sqlite3 компилуется or качивается pre-built binary при установке — нuj other system dependencies.

git clone https://github.com/gonzalonicolasr/cortexmem.git
cd cortexmem
npm install
npm test          # optional: 216 tests, ~1s

Или установите его без clone — you get a cortexmem command in your PATH:

npm install -g github:gonzalonicolasr/cortexmem
cortexmem --version

Смок-тест as an ordinary CLI:

node bin/memoria.mjs save "Fix hydration bug" \
  --type bug_fix --what "moved the fetch out of useEffect" \
  --project demo --learned "SSR/CSR mismatch, not a race condition"

node bin/memoria.mjs search hydration --project demo
node bin/memoria.mjs stats

Вот и вс — on first write the database is created at ~/.memoria/memoria.db.

Подключите к своему агенту

Cortex и MCP speak over stdio. If установлен глобально command is cortexmem mcp; if from the clone, use node with the absolute path to bin/memoria.mjs.

<detекtail open>

claude mcp add cortex -- node /absolute/path/to/cortexmem/bin/memoria.mjs mcp
claude mcp list | grep cortex     # → ✓ Connected

[mcp_servers.cortex]
command = "node"
args = ["/absolute/path/to/cortexmem/bin/memoria.mjs", "mcp"]

{
  "mcpServers": {
    "cortex": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/cortexmem/bin/memoria.mjs", "mcp"]
    }
  }
}

For pi you need установить MCP expansion and contents укажите ему the same command/args паре, как in the JSON example above. For HTTP transport сoviet [docs/self-hosting.md] (docs/self-host.md).

Пкестart client после change in конog — Codex and Clаude Code do not пе recitating config on hot.

Научите агенту реально им пользоваться

Только инструментов тung: агнту must знаем, when to save. Copy CLAUDE.md (memory protocol) into the file of instructions for your agent (CLAUDE.md, AGENTS.md, .cursorrules, pi's AGENTS.md, ...). It's about ~40 lines and instructs the agent to automatically save after bug fixes, decisions, three institutional discoveries and changes the config. And also call memoria_context at the start of the session.

CLI

memoria mcp                    Start the MCP server (stdio)
memoria serve [port]           Start the HTTP API (default 7437, loopback-only)
memoria save <title> [flags]   Save a memory
memoria search <query>         Full-text search
memoria context [project]      Print the project context block
memoria recent [flags]         Recent memories
memoria stats                  Counts by type / project
memoria projects               List projects
memoria decay                  Apply relevance decay

Флаги: --project --type --limit --what --why --where --learn --topic.

Серверный режим

Want one memory common to all your machines / agents at home? Raise the HTTP server and "h" before it put an обратный proxy:

MEMORIA_HOST=127.0.0.1 MEMORIA_AUTH_TOKEN=$(openssl rand -hex 24) \
  node bin/memoria.mjs serve 7437
curl -s localhost:7437/api/health

Reference to endpoint: docs/http-api.md). systemd unit, bearer auth, embeddings backfill, reflections cron and backups: docs/self-hosting.md.

⚠️ HTTP-сервер trusts the X-Workspace-Id header (multi-tenant architecture: upstream proxy provergives polьзователя and подставляетвает его). ** Не бинqvivare him на публичный интерфейс без MEMORIA_AUTH_TOKEN + проkси перед ним.**

Семантиeckий поиск (optional)

npm install @xenova/transformers          # already an optionalDependency
export MEMORIA_SEMANTIC_SEARCH=1
node bin/backfill-embeddings.mjs          # embed existing memories

The model downloads once (~22 MB) and runs on CPU. C flag enabled commands memoria_search и memoria_recall are hybrid (FTS5 + KNN and merged by means of Reciprocal Rank Fusion); option disabled everything as pure keyword search. For memories not Navigator on:languageMEMORIA_EMBODDING_MODEL=Xenova/paraphrase-multilinguache-MiniLM-L12-v2` before foreign/backfill (same 384 measurements) — see semantic search.

Переменные окружения

Квоты

По умолчанию quotas are rated for multi-tentan hosted: 1,000 active memories, 10 MB text, 50 projects, 5 active sessions, 32 KB per memory. For personal local «installation» remove limits:

export MEMORIA_UNLIMITED_WORKSPACES=1   # workspace 1 = the CLI/stdio default

MCP инструменты

Text in— Troops use thememoria_` prefix (the project's original name) to maintain النجاح with older installed agents.

Data, Тайнность, бэкапы

Зbase only no file (WAL mode). Smake backup: sqlite3 ~/.memoria/memoria.db ".backup out.db". Секрты удалются до after записи к строки: ключи AWS, GitHub / GitLab PAT, OpenAI / Anthropic / Slack / Google / Stripe / Cloudflare keys, JWT, SSH private keys — and everything, which you wrap in <private>...</private>. This is a security circuit, not a privilege to paste secrets.

• The source code on your машине can not publish your rowa — unless you restart the HTTP server and open it.

Development

npm test          # vitest, 216 tests
npm run test:watch

Мультиязычные tests of embeddings interface hidden behind MEMORIA_TEST_MULTILINGUAL=1, so you don't need to download any model. Changelog: [CHAGELog.md][CHAGELOG.md].

Hosted (optional)

If you prefer not to launch any scenario, the same engine is hosted at cortexmem.com: sign up, copy cc_... API key from the panel and point the client at the HTTP endpoint instead of the local command:

claude mcp add cortex https://cortexmem.com/api/cortex/mcp \
  --transport http --header "Authorization: Bearer cc_YOUR_KEY"

# ~/.codex/config.toml
[mcp_servers.cortex]
url = "https://cortexmem.com/api/cortex/mcp"

[mcp_servers.cortex.http_headers]
Authorization = "Bearer cc_YOUR_KEY"

Сelf-hosting max." — Self-hosting все features are preserved; hosted version adds web panel and a "brain graph", but the memory itself.

"License"

MIT © Gonzalo Rocca — see [LICENSE][LICENSE].