pulse8-ai-cortex-knowledge-vault

Purpose

PULSE8.ai Cortex is an open-source knowledge layer for AI agents, designed to enable agents to accumulate, evolve, and reuse persistent knowledge instead of re-deriving it on every query. It is built on plain Markdown files, combining Git-native memory, a typed knowledge graph, and MCP retrieval, so agents can build, evolve, and reuse knowledge.

Key Capabilities

• Shared knowledge base: Provides a unified Markdown knowledge base for AI agents and humans, with no proprietary format and no lock-in.
• Typed knowledge graph: Automatically maintains knowledge nodes and relationships through wikilinks, tags, and typed edges (such as derived_from). Node types include note, agent_def, session, daily, and feedback.
• Full-text and hybrid search: Keyword/semantic search is provided by QMD, and Cortex then supplements it with graph edges (wikilinks, tags, relationships) to enhance results.
• LLM-driven file compilation: Uses MarkItDown to convert formats such as PDF, DOCX, PPTX, XLSX, HTML, CSV, JSON, XML, images (EXIF/OCR), and plain text into Markdown.
• MCP access: Integrates with any compatible AI client through the MCP protocol, supports streamable HTTP and stdio, and mirrors the REST API 1:1 (/api/v1/).
• Persistent memory: Files can persist across sessions, deployments, and model upgrades.
• Git versioning: The knowledge base is a plain Markdown directory, naturally supporting diffs and version control.
• No database: It can run without a dedicated database or graph database.
• Resources as tool input: Supports keeping large tool outputs on the server side and passing lightweight handles between tools, reducing LLM context window usage.
• Determinism first: Ingestion, the knowledge graph, and search all work with zero LLM calls; LLMs are used only for optional enhancements such as cross-references, tags, and image descriptions.
• Daily activity log: Every write, ingestion, and successful compilation event is automatically mirrored to that day's UTC daily note.
• Batch ingestion: Provides a one-click script that can recursively read local directories, deduplicate by SHA-256, and concurrently compileand rebuild the index.

Usage

Docker is required. The OpenRouter API key is optional and is used only for LLM-driven cross-referencing of Wiki articles; file conversion works out of the box and does not require an API key.

After cloning the repository, start it via the script, and connect an MCP client (such as Claude Desktop) to http://localhost:8420/mcp/。停止使用脚本。

On macOS, native QMD mode can be run to utilize the Metal GPU; Cortex-only mode can also be used to connect to an external QMD; Linux + NVIDIA GPU environments support GPU-accelerated QMD.

Authentication supports two methods: API Key (AUTH_METHOD=apikey) and Microsoft Entra ID (AUTH_METHOD=oidc), protecting the REST API and MCP endpoints.

The LLM backend can be selected via the LLM_BACKEND environment variable, including local Ollama or a fully deterministic mode (LLM_BACKEND=none).

The project implements an MCP resource mode: by passing as_resource: true in vault_search or vault_context, it can be read via the MCP resource protocol, the vault_resource_read fallback tool, or the REST interface.

Applicable Scenarios

• Persistent memory for AI agents
• Shared knowledge across multiple agents
• Git-versioned organizational knowledge
• MCP-compatible knowledge retrieval
• Knowledge graphs without the need for a dedicated graph database
• Long-term accumulation of organizational policy knowledge
• Human-AI collaborative knowledge management

Specific use cases include: software engineering knowledge bases (architecture decision records, coding standards, engineering handbooks, platform documentation, domain-driven design models); banking and financial services (product documentation, regulatory compliance knowledge, business domain models, wealth management knowledge, institutional process knowledge); enterprise knowledge management (project documentation and retrospectives, lessons learned, organizational memory, best practices and playbooks); AI agent memory layers (cross-agent shared memory, long-term reasoning context, cross-session knowledge accumulation, multi-agent collaboration).

Limitations

The project explicitly lists scenarios for which it is not suitable:

• Simple full-text document search (a search engine should be used)
• Pure vector retrieval without a graph (a vector database should be used)
• Ephemeral, stateless conversations
• Workflows that do not require persistent knowledge evolution

Other facts: Docker Desktop on macOS cannot expose the Metal GPU to containers; containerized QMD uses only the CPU and is more than an order of magnitude slower on non-simple knowledge bases. The project measured 45.0% overall accuracy on LongMemEval-S (500 questions, full haystacks, hybrid search), 65.6% evidence recall@8, zero review errors. More information regarding fees, pricing, specific platform support, etc. is not yet available.