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.

3. 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