Project Guardian MCP

Part of the HeLa MCP Ecosystem — This server is HeLa Genome (hela-genome) — the State & Memory component of the HeLa cellular architecture. See the ecosystem docs for profiles, workflows, and multi-client setup.

A Model Context Protocol (MCP) server for persistent project memory, knowledge-graph operations, SQLite data access, runtime security checks, and guided project-management workflows. The current registry exposes 38 tools, 11 resources, and 27 prompts.

Table of Contents

• Features
  • Project Guardian Memory System
  • Streamlined Database Operations
  • Runtime Companion Integration
  • AI Guidance System
  • Advanced Features
  • Enterprise Features
• Requirements
• Installation
• Available Tools
  • Database Operations (7 tools)
  • Memory and Guidance Tools (15 tools)
  • Runtime Companion Tools (12 tools)
  • UI Tools (4 tools)
• AI Guidance System
  • Available Resources
  • Available Prompts
  • How AI Models Use Guidance
• Usage Examples
  • Project Guardian Setup
  • Project Management Workflow
  • Database Operations
• Configuration
  • Optional Runtime Services
  • For Cursor IDE
  • For Claude Desktop
• Project Structure
• Development
• License

Features

Project Guardian Memory System

• Knowledge Graph: Maintain project entities, relationships, and observations

• Entity Management: Projects, tasks, people, resources with rich metadata

• Relationship Mapping: Dependencies, ownership, blockers, and connections

• Observation Tracking: Contextual notes and progress updates

• Progressive Disclosure Retrieval: search_nodes supports tiered retrieval via detailLevel: compact | summary | full. Compact mode returns IDs, types, observation counts, and 1-line previews (~50 tokens) to prevent context window bloat, followed by on-demand deep recall via open_node.

• Pre-File Context & Timeline: Call get_file_context before reading or refactoring a file to review prior modifications, linked tasks (implements), and open bugs (affects). Call get_timeline for chronological event feeds.

• Privacy Guardrails: Built-in stripping of <private>...</private> and <!-- private --> tags before persisting observations or indexing into vector embeddings.

• Zero-Touch Lifecycle Hooks: Shell/Node scripts under hooks/ (session-start.mjs, post-tool-run.mjs) enable automated context injection and change tracking for Claude Code, Cursor, and Git hooks.

• Semantic Search: Fast, localized RAG matching via SQLite's native FTS5 extension (MATCH and bm25() ranking) across entity names, types, and observations

• Per-Project Memory: Each project gets its own memory.db. The server resolves the project root in this order: the GUARDIAN_PROJECT_ROOT environment variable, then the Git toplevel of its working directory, then $XDG_DATA_HOME/project-guardian as a shared fallback outside any Git repository

• Central Memory Mirror: Every memory write also syncs into one central database at ~/memory/memory.db, giving an aggregated, searchable map across all projects and a fallback when a project database is unavailable. Reads through read_graph and search_nodes merge both stores, with project entries taking precedence

• Daily Central Backups: On the first sync of each day, the central database is snapshotted to ~/memory/backup/ddmmyyyy_memory.db; the seven most recent backups are kept and older ones pruned automatically. On first run, a legacy ~/memory.db in the home directory is migrated into the new layout and used to seed the first backup

• On-Demand Pre-Commit Setup: Nothing is installed at startup. Call setup_pre_commit when you want a generated .pre-commit-config.yaml and Git hooks in the active project

• Optional Obsidian Vault Mirror: When HELA_GENOME_OBSIDIAN_VAULT is set, entity/relation/observation writes are mirrored as Markdown notes with YAML frontmatter into an Obsidian vault, so humans can browse and edit project memory in Obsidian (graph view, backlinks). SQLite remains the base engine; the web UI dashboard has been removed in favor of Obsidian.

Harness Session Bridge

• Read-only ingestion from 8 agent harnesses: opencode, kilocode, zed, delta, antigravity, cursor, vscode, codex. Sources are opened read-only (SQLite OPEN_READONLY, capped JSONL scans) — the bridge never writes to harness stores and never touches harness processes.
• What's harvested: session titles, summaries/previews, timestamps, project directories, models, message/step counts. Full transcripts and binaries are never ingested.
• Secret redaction first: API keys, tokens, bearer credentials, private keys, and password assignments are replaced with [REDACTED] before anything reaches the graph.
• Incremental + idempotent: per-session watermarks in a harness_sync table — re-runs only pick up new or updated sessions; dryRun previews without writing.
• Absent stores are honest: harnesses with no local store on the machine (e.g. Cursor/VS Code when not installed) report found: false instead of failing. Store paths are overridable via HARNESS_<ID>_PATH.

Streamlined Database Operations

• Two Stores, One Interface: Every project uses its own memory.db; all seven database tools can also address the central aggregate with database: "central"
• Core CRUD: Essential database operations (query, insert, update, delete)
• SQL Execution: Direct SQL query execution
• Data Transfer: Import/export CSV and JSON files
• 25 Canonical Tools + 14 Legacy Aliases: Seven database tools, nine memory/guidance tools (initialize_memory, memory_edit, read_graph, read_graph_stream, search_nodes, open_node, get_file_context, get_timeline, get_project_guidance), and nine runtime tools (sync_central_memory, set_project_root, setup_pre_commit, get_session_context, analyze_git_changes, inspect_untrusted_text, security_scan, cache, harness_sessions). The view-only Web UI dashboard has been removed in favor of the optional Obsidian vault mirror. Legacy names such as create_entity remain as deprecated aliases that normalize to canonical actions

Runtime Companion Integration

The repository includes six guardian-* AgentSkills and exposes their operational capabilities through typed MCP tools:

| Companion | Runtime role | MCP surface | | --- | --- | --- | | guardian-memory | Persistent entities, relations, and observations | Twelve memory tools | | guardian-session | Active-task, bug, blocker, and recent-change summaries | get_session_context | | guardian-tracker | Bounded Git diff and untracked-file analysis | analyze_git_changes | | guardian-wall | Untrusted-text normalization and prompt-injection detection | inspect_untrusted_text | | guardian-security | Secret scanning and Trivy image scanning | scan_project_secrets, scan_container_image | | guardian-cache | Optional namespaced Redis storage | Four cache_* tools |

AgentSkills provide host-side workflows and instructions. The MCP runtime implements the corresponding operations directly in TypeScript, except container scanning, which invokes Trivy as a bounded external process. No generic script or shell execution tool is exposed.

AI Guidance System

• 11 Resources: Templates, best practices, project status, and companion capability health
• 27 Prompts: Comprehensive pre-built workflows for all aspects of project management
• Expert Guidance: Step-by-step instructions for complex operations
• Contextual Help: Adaptive prompts based on user needs
• Knowledge Base: Comprehensive project management wisdom

Advanced Features

• Schema Validation: Comprehensive input validation with Zod schemas
• Error Handling: Detailed error messages and graceful failure handling
• Connection Management: Bounded 20-connection LRU cache with WAL + synchronous=NORMAL + cache_size=-64000 + journal_size_limit=67108864 + temp_store=MEMORY + busy_timeout=5000, monthly VACUUM (POST /api/vacuum) and shutdown cleanup
• File Integration: CSV and SQL imports are streamed; CSV writes use bounded string assembly
• Result Limits & Pagination: Unbounded raw SELECT capped at 10,000 rows; read_graph/readStore default 5000 with ?limit=&offset=, read_graph_stream cursor 500/page via GET /api/graph/stream?cursor=&limit=& + POST /api/vacuum, search_nodes capped 100 (hybrid RRF k=60)

Enterprise Features

• TypeScript: Fully typed with comprehensive error handling
• Input Validation: Zod schema validation for all parameters
• Error Recovery: Graceful error handling with detailed error messages
• Resource Management: Automatic cleanup of connections and resources
• Testing: Fourteen Jest suites with 153 passing tests (WAL + pagination + close_ui + read_graph_stream + e2e-vector hybrid)

Requirements

• Node.js: >= 18.0.0
• npm: Latest stable version
• SQLite3: Automatically installed as dependency
• Redis: Optional; required only for cache_* tools through REDIS_URL
• Trivy: Optional; required only for scan_container_image

Installation

1. Clone the repository:

git clone https://github.com/Hela-Ecosystem/project-mcp.git
cd project-mcp

2. Install dependencies:

npm install

3. Build the project: Choose between development or production build:

For development (includes source maps and full TypeScript compilation):

npm run build

For production (creates an optimized, minified bundle):

npm run build:prod

4. Run the test suite:

npm test

5. Start the server:

npm start

Updating After Changes

When you pull new updates or modify the code, you must rebuild the server and restart your MCP client (Cursor, Claude Desktop, etc.) for the changes to take effect:

1. Pull the latest code: git pull
2. Install new dependencies (if any): npm install
3. Rebuild the bundle: npm run build:prod
4. Important: Restart your IDE or the MCP connection so the client can fetch the newly updated tools and prompts.

Available Tools

This MCP server currently provides 38 tools:

Tool reference note: sections below preserve legacy entry points for compatibility. The canonical surface