Pulse8 AI Cortex Knowledge Vault

PULSE8.ai Cortex

The open-source knowledge layer for AI agents

Knowledge that compounds.

PULSE8.ai Cortex is the open-source knowledge layer for AI agents: Git-native memory, a typed knowledge graph, and MCP-powered retrieval on top of plain Markdown — so agents can build, evolve, and reuse persistent knowledge instead of re-deriving it on every query.

Under the hood it's a unified vault for AI agents and humans, backed by a typed knowledge graph, full-text + hybrid search, and a MarkItDown-powered file compiler. Drop files in (PDF, DOCX, PPTX, XLSX, HTML, images, and more), let agents read, write, search, link, and compile knowledge — no database required.

Inspired by Andrej Karpathy's LLM Wiki pattern — a persistent, compounding knowledge base maintained by LLMs instead of re-derived on every query. Search powered by Tobi Lütke's QMD.

---

Why PULSE8.ai Cortex?

Most AI agents can access tools, but they cannot accumulate knowledge.

Traditional RAG systems retrieve documents. PULSE8.ai Cortex builds a persistent, evolving knowledge layer that grows over time and becomes more valuable the more agents and humans interact with it.

With PULSE8.ai Cortex, agents can:

• Learn from interactions — every read, write, ingest, and compile event is logged and graph-linked
• Build and traverse knowledge graphs — wikilinks, tags, and typed edges, maintained automatically
• Store structured insights — Markdown notes with typed nodes (note, agent_def, session, daily, feedback)
• Retrieve context across projects — vault_context builds a ranked subgraph from any seed query
• Share knowledge through MCP — one vault, every MCP-compatible client
• Maintain long-term memory — files survive sessions, deployments, and model upgrades
• Version knowledge through Git — the vault is a plain directory of Markdown, diff-friendly out of the box

When to use PULSE8.ai Cortex

Ideal use cases

• ✅ Persistent memory for AI agents
• ✅ Shared knowledge across multiple agents
• ✅ Git-versioned organisational knowledge
• ✅ MCP-compatible knowledge retrieval
• ✅ Knowledge graphs without a dedicated graph database
• ✅ Long-term accumulation of institutional knowledge
• ✅ Human + AI collaborative knowledge management

Not ideal for

• ❌ Simple full-text document search (use a search engine)
• ❌ Pure vector-only retrieval with no graph (use a vector DB)
• ❌ Short-lived, stateless conversations
• ❌ Workflows that don't need persistent knowledge evolution

PULSE8.ai Cortex vs alternatives

Works with

PULSE8.ai Cortex speaks MCP — so it plugs into any AI client that does. The same vault is reachable over streamable HTTP or stdio, and mirrored 1:1 by a REST API at /api/v1/.

Because the vault is just files, humans and agents collaborate on the same knowledge — no proprietary format, no lock-in.

Get started

[!NOTE]

PULSE8.ai Cortex requires Docker. An OpenRouter API key is optional — needed only for LLM-powered cross-referencing between wiki articles. File conversion works out of the box without any API key.

1. Clone the repository:

    git clone https://github.com/synpulse8-opensource/pulse8-ai-cortex-knowledge-vault.git

cd cortex-knowledge-vault

2. Launch PULSE8.ai Cortex:

    ./scripts/start.sh

This builds and starts both PULSE8.ai Cortex (API + MCP on :8420) and QMD (search on :3100), waits for health checks, and you're ready to go.

1. Connect your MCP client (e.g. Claude Desktop) to http://localhost:8420/mcp/.

To stop: ./scripts/stop.sh

Native QMD mode (macOS / Metal GPU)

Docker Desktop on macOS cannot expose the Metal GPU to containers, so containerized QMD embeds on CPU only — over an order of magnitude slower on non-trivial vaults. Run QMD natively instead; the qmd binary uses Metal automatically:

# One-time: install the qmd binary

brew install tobi/tap/qmd # or: npm install -g @tobilu/qmd

Start native QMD (background daemon) + Cortex in Docker

./scripts/start.sh --native-qmd

The QMD daemon's pid and log are kept in .qmd-native.pid / .qmd-native.log. To stop both: ./scripts/stop.sh --native-qmd (a plain ./scripts/stop.sh also cleans up a native QMD if one is running).

Cortex-only mode (external QMD)

If you manage QMD yourself (already running elsewhere), start only the Cortex container:

./scripts/start.sh --cortex-only   # set QMD_URL in .env if not http://host.docker.internal:3100

To stop: ./scripts/stop.sh --cortex-only

GPU-accelerated QMD (EC2 / Linux with NVIDIA GPU)

For production deployments with NVIDIA GPU acceleration:

docker compose -f docker-compose.yml -f docker-compose.gpu.yml up --build -d

See docs/ec2-gpu-setup.md for a full guide on instance selection, NVIDIA toolkit installation, and cost estimates.

Features

Benchmarks

45.0% overall accuracy on [LongMemEval-S](https://github.com/xiaowu0162/LongMemEval) (500 questions, full haystacks, hybrid search) with 65.6% evidence recall@8 and zero judge errors — measured end-to-end through the pu