Post Cortex

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.
• Graph-RAG — search results enriched with entity-graph traversal and relationship paths
• Knowledge Graph — every write carries typed entities + relations (post-0.3.0 MCP contract); 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
• Non-blocking writes — writes return as soon as the entry is durably persisted; embeddings + entity-graph merge + summary refresh land on a bounded background pipeline. Single-digit ms write latency on warm paths.
• Privacy-first — all processing runs locally, no external API calls
• Lock-free Rust core — O(log n) HNSW vector search, ArcSwap session state, atomic CAS write path
• 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:

Crate	Pick when you need…	crates.io
post-cortex	The full stack in one dep
post-cortex-core	Domain types + traits only (no I/O, no ML)
post-cortex-proto	gRPC wire types (client-side)
post-cortex-embeddings	Model2Vec (default) + BERT embedders + HNSW vector DB
post-cortex-storage	RocksDB + SurrealDB backends
post-cortex-memory	ConversationMemorySystem orchestrator
post-cortex-mcp	MCP tool functions (embed in any MCP host)
post-cortex-daemon	pcx CLI + rmcp/axum/tonic server

Dependency graph (acyclic):

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

post-cortex-core carries no transport / I/O / ML dependencies — downstream Rust projects can take it for the type system alone without dragging in RocksDB, Candle, or the server stack.

Installation

# Cargo (any platform with Rust 1.90+) — 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.3"

# 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 + HNSW 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

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

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 for enforcement, and installs agent definitions. See Usage Guide for details.

3. Start Coding

claude

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

MCP 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 line is 0.3.0 — Model2Vec default + non-blocking write pipeline + canonical single-entrypoint write path. See CHANGELOG.md for the full diff and migration notes.

License

MIT — see LICENSE.