AI助手持久记忆服务器

Post-Cortex

Persistent Memory for AI Assistants

Post-Cortex is an MCP server that gives AI assistants long-term memory. It stores conversations, decisions, and insights in a searchable knowledge base with automatic entity extraction.

Features

• Persistent Memory — conversations survive across sessions
• Semantic Search — potion-multilingual-128M (Model2Vec) by default. ~50 MB on disk, ms-per-text inference, multilingual (Latin / Cyrillic / CJK / Greek / Arabic) out of the box. Heavier BERT models stay available behind the bert feature.
• Measured retrieval — vector + BM25 search fused with RRF, an optional local cross-encoder or Voyage reranker (mode: fast / local / accurate), and each hit returned with its neighbouring records. LoCoMo all@50: 0.793 / 0.878 / 0.936
• Graph-RAG — search results enriched with entity-graph traversal and relationship paths
• Conversation capture (opt-in) — a Claude Code hook keeps the raw turns in a per-session message stream, searchable apart from the records (sources: records / messages / all); records can link to the turns they came from (derived_from)
• Cards — a short, versioned project card per workspace and a user card, put in front of every session
• Authorship — records and messages carry who wrote them; search can filter by author or prefer one
• Knowledge Graph — every write carries typed entities + relations (MCP contract since 0.3.0); the graph stays in sync with the prose
• Single-entrypoint architecture — every transport (gRPC, MCP, future REST) routes through the same canonical MemoryServiceImpl::update_context; no parallel codepaths to drift between
• Durable, non-blocking writes — a write returns once the storage backend has acknowledged it (durable in the response); embeddings + entity-graph merge + summary refresh land on a bounded background pipeline. Persists are coalesced and ordered per session.
• Redaction — credentials, e-mail addresses, phone numbers and public IPv4 addresses become [REDACTED:<kind>] before storage, on every transport (on by default; PC_REDACT=0 disables)
• Auth + Host allowlist — optional bearer token (PC_AUTH_TOKEN) on HTTP and gRPC; /mcp and /api/* reject unknown Host headers (DNS-rebinding protection, PC_ALLOWED_HOSTS)
• Privacy-first — all processing runs locally (the embedding and reranker models are downloaded from Hugging Face once, on first use); the only external API is the opt-in Voyage reranker
• Lock-free Rust core — ArcSwap session state, atomic CAS write path; vector search is an exact top-k scan up to 10 000 vectors and HNSW above that, with per-session indexes
• Flexible storage — RocksDB (embedded, default) or SurrealDB (local / remote, distributed)

Workspace layout

This repository is a Cargo workspace of 8 publishable crates. Pick the one that matches your need — depending on the facade post-cortex pulls everything, but most consumers only want a subset:

Dependency graph (acyclic):

post-cortex-proto ──► post-cortex-core ──► post-cortex-storage ◄── post-cortex-embeddings
                                                  │                        │
                                                  ▼                        │
                                           post-cortex-memory ◄────────────┘
                                                  │
                                                  ▼
                                           post-cortex-mcp
                                                  │
                                                  ▼
                                           post-cortex-daemon
                                                  │
                                                  ▼
                                           post-cortex (facade)

A ──► B means B depends on A. post-cortex-embeddings depends on no other workspace crate.

post-cortex-core carries no storage, ML or server dependencies (only tonic / prost through post-cortex-proto) — downstream Rust projects can take it for the type system alone without dragging in RocksDB, Model2Vec / Candle, or the server stack.

Installation

# Cargo (any platform with Rust 1.95+) — ships the pcx CLI from crates.io
cargo install post-cortex-daemon --features "embeddings,surrealdb-storage"

# Homebrew (macOS / Linux)
brew install julymetodiev/tap/post-cortex

# Or download a prebuilt binary from a release
curl -L https://github.com/julymetodiev/post-cortex/releases/latest/download/pcx-aarch64-apple-darwin -o /usr/local/bin/pcx
chmod +x /usr/local/bin/pcx

As a library

[dependencies]
# Everything in one dep — pulls the full stack including the daemon.
post-cortex = "0.5"

# Or pick the leanest crate for your use case:
# - post-cortex-core           — types + traits only (no I/O, no ML)
# - post-cortex-mcp            — MCP tool functions, embed in any MCP host
# - post-cortex-embeddings     — Model2Vec + vector DB, no orchestrator
# - post-cortex-memory         — ConversationMemorySystem + canonical service

Quick Start

1. Configure MCP (once, globally)

# HTTP transport (recommended, requires daemon running)
claude mcp add --scope user --transport http post-cortex http://127.0.0.1:3737/mcp \
  --header "X-PCX-Author: claude-code"

# Or stdio transport (no daemon needed)
claude mcp add --scope user --transport stdio --env PC_AUTHOR=claude-code post-cortex -- pcx

X-PCX-Author / PC_AUTHOR names who the records come from when a write does not say; MCP clients often report only their SDK's name.

This registers Post-Cortex for all projects on your machine.

2. Set Up Your Project

pcx setup

This creates a session, workspace, CLAUDE.md with memory rules, hooks (a log check on Stop, the cards on SessionStart) and the post-cortex-memory skill. pcx setup --capture also installs the conversation capture hook; --daemon-url / --capture-url point the hooks at a daemon on another host. See Usage Guide for details.

3. Start Coding

claude

Claude will automatically search past knowledge before answering and log new discoveries.

MCP Tools

Nine tools:

Daemon Mode

For multiple Claude instances sharing the same memory:

pcx start    # Start daemon
pcx status   # Check status
pcx stop     # Stop daemon

Configure Claude for HTTP transport:

{
  "mcpServers": {
    "post-cortex": {
      "type": "http",
      "url": "http://localhost:3737/mcp"
    }
  }
}

See Daemon Mode docs for details.

Data Export/Import

pcx export --output backup.json       # Full export
pcx export --output backup.json.gz    # Compressed
pcx import --input backup.json        # Import

Storage Backends

Configure in ~/.post-cortex/daemon.toml. See Daemon Mode docs.

Environment Variables

Development

# Build the workspace with the full feature set
cargo build --release --features "embeddings,surrealdb-storage"

# Run the unit-test suite (no network, no external state)
cargo test --workspace --lib

# Run the live E2E test against a real SurrealDB + HuggingFace Hub
# (ignored by default; needs POST_CORTEX_E2E_SURREAL_* env vars and
#  ~50 MB potion-multilingual-128M download on first run)
POST_CORTEX_E2E_SURREAL_USER=root \
POST_CORTEX_E2E_SURREAL_PASS=root  \
cargo test -p post-cortex --features "embeddings,surrealdb-storage" \
    --test integration_e2e_surrealdb -- --ignored --nocapture

# Benchmarks
cargo bench

Supply-chain hygiene

• cargo fmt --all --check
• cargo clippy --workspace --all-targets --all-features -- -D warnings
• cargo deny check — see deny.toml
• cargo audit — see .cargo/audit.toml

CI enforces all four on every push to main.

Release notes

The current release is 0.5.0 — the measured retrieval pipeline (BM25, rerankers, search modes, neighbours), conversation capture, project and user cards, and authorship on records and messages.

Before upgrading:

• SurrealDB: back up the database first; the daemon adds the full-text index and the message and card tables on start.
• RocksDB: older data loads as is; data written by 0.5.0 is not readable by older binaries.
• Local reranker on Linux: install ONNX Runtime 1.31 and set ORT_DYLIB_PATH to libonnxruntime.so. With reranker_model set and no search_mode, searches default to local (~1 s); set search_mode = "fast" to keep the old latency and ask for local per call.

Upgrading from 0.3? See the 0.4.0 notes in the changelog (allowed_hosts for wildcard binds, the forward-only SurrealDB schema).

See CHANGELOG.md for the full diff and migration notes.

License

MIT — see LICENSE.