Project Guardian MCP
Provides comprehensive tools for managing project memory, including direct SQL query execution, core CRUD operations, and persistent knowledge graph storage using a SQLite database.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Project Guardian MCP
MCP server: hela-genome · Version: 3.0.6 · Canonical tools: 31. Current tool reference.
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 29 canonical tools, 11 resources, and 27 prompts.

Table of Contents
Related MCP server: Engram
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_nodessupports tiered retrieval viadetailLevel: 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 viaopen_node.Pre-File Context & Timeline: Call
get_file_contextbefore reading or refactoring a file to review prior modifications, linked tasks (implements), and open bugs (affects). Callget_timelinefor 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 (
MATCHandbm25()ranking) across entity names, types, and observationsPer-Project Memory: Each project gets its own
memory.db. The server resolves the project root in this order: theGUARDIAN_PROJECT_ROOTenvironment variable, then the Git toplevel of its working directory, then$XDG_DATA_HOME/project-guardianas a shared fallback outside any Git repositoryCentral 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 throughread_graphandsearch_nodesmerge both stores, with project entries taking precedenceDaily Central Backups: On the first sync of each day, the central database is snapshotted with SQLite's online backup API and integrity-checked before publication to
~/memory/backup/ddmmyyyy_memory.db; the seven most recent backups are kept. Legacy~/memory.dbmigration uses the same snapshot procedure and retains the original for recovery.On-Demand Pre-Commit Setup: Nothing is installed at startup. Call
setup_pre_commitwhen you want a generated.pre-commit-config.yamland Git hooks in the active projectOptional Obsidian Vault Mirror: When
HELA_GENOME_OBSIDIAN_VAULTis 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 (SQLiteOPEN_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_synctable — re-runs only pick up new or updated sessions;dryRunpreviews without writing.Absent stores are honest: harnesses with no local store on the machine (e.g. Cursor/VS Code when not installed) report
found: falseinstead of failing. Store paths are overridable viaHARNESS_<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 withdatabase: "central"Core CRUD: Essential database operations (query, insert, update, delete)
SQL Execution: Direct SQL query execution
Data Transfer: Import/export CSV and JSON files
31 Canonical Tools + 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), three fleet mission tools (create_mission,list_missions,update_mission), two search-feedback tools (search_feedback,search_priors), and ten runtime tools (includingobsidian_vault). The view-only Web UI dashboard has been removed in favor of the optional Obsidian vault mirror. Legacy names such ascreate_entityremain 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 |
| Persistent entities, relations, and observations |
|
| Active-task, bug, blocker, and recent-change summaries |
|
| Bounded Git diff and untracked-file analysis |
|
| Untrusted-text normalization and prompt-injection detection |
|
| Secret scanning and Trivy image scanning |
|
| Optional namespaced Redis storage |
|
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, maintenance and shutdown cleanup. The removed web UI's REST routes are not a supported interface.File Integration: CSV and SQL imports are streamed; CSV writes use bounded string assembly
Result Limits & Pagination: Raw
SELECTresults are bounded; use the MCPread_graph,read_graph_stream, andsearch_nodesschemas for supported pagination and search limits, rather than removed UI HTTP routes.
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: The current isolated regression run passes 19 suites / 264 tests, including vault conflicts, replicated timestamp/observation/relation-order convergence, typed request/import validation, SQL binding validation, WAL-safe backups, mission contention, and vector retrieval. Historical UI tests do not imply an available UI service.
npm run lintchecks every source TypeScript file and fails on any warning; the current run has zero errors and zero warnings.
Requirements
Node.js: Node 22 LTS is the validated ecosystem environment; see
package.jsonfor the package's declared standalone engine range.npm: Latest stable version
SQLite3: Automatically installed as dependency
Redis: Optional; required only for
cacheactions throughREDIS_URLTrivy: Optional; required only for
security_scanwithaction: "container"
Installation
Clone the repository:
git clone https://github.com/Hela-Ecosystem/project-mcp.git
cd project-mcpInstall dependencies:
npm installBuild the project: Choose between development or production build:
For development (includes source maps and full TypeScript compilation):
npm run buildFor production (creates an optimized, minified bundle):
npm run build:prodRun the test suite:
npm testStart the server:
npm startUpdating 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:
Pull the latest code:
git pullInstall new dependencies (if any):
npm installRebuild the bundle:
npm run build:prodImportant: Restart your IDE or the MCP connection so the client can fetch the newly updated tools and prompts.
Available Tools

This MCP server currently advertises 29 canonical tools. The generated tool reference lists their names and consolidated actions.
Tool reference note: sections below preserve legacy entry points for compatibility. The canonical surface is 29 tools (added
obsidian_vaultand 3 fleet mission toolscreate_mission,list_missions,update_mission; removedui_serverin favor of the Obsidian vault mirror). Legacy names such ascreate_entityandcache_getnormalize to canonical actions and emit a deprecation warning. Section counts include those aliases.
Database Operations (7 tools)
All database tools accept an optional database selector: project (default) targets the active project's memory.db, central targets the central aggregate at ~/memory/memory.db.
execute_sql - Execute SQL Query
Execute raw SQL queries on the selected memory database.
Parameters:
query(required): SQL query stringparameters(optional): Query parameters arraydatabase(optional):"project"or"central", default"project"
query_data - Query Table Data
Query memory tables with filtering and pagination.
Parameters:
table(required): Table nameconditions(optional): WHERE conditions objectlimit(optional): Maximum rows to returnoffset(optional): Number of rows to skiporderBy(optional): Column to sort byorderDirection(optional): Sort direction ("ASC" or "DESC")database(optional):"project"or"central", default"project"
insert_data - Insert Records
Insert records into a memory table.
Parameters:
table(required): Table namerecords(required): Array of record objects to insertdatabase(optional):"project"or"central", default"project"
update_data - Update Records
Update records in a memory table.
Parameters:
table(required): Table nameconditions(required): WHERE conditions for records to updateupdates(required): Fields to updatedatabase(optional):"project"or"central", default"project"
delete_data - Delete Records
Delete records from a memory table.
Parameters:
table(required): Table nameconditions(required): WHERE conditions for records to deletedatabase(optional):"project"or"central", default"project"
import_data - Import Data
Import data from CSV or JSON file into a memory table.
Parameters:
table(required): Target table namefilePath(required): Workspace-relative path to the source file (absolute paths and..traversal are rejected unlessHELA_GENOME_ALLOW_EXTERNAL_PATHS=true)format(optional): File format ("csv" or "json")options(optional): Import options (delimiter, hasHeader)database(optional):"project"or"central", default"project"
export_data - Export Data
Export memory table data to CSV or JSON file.
Parameters:
table(required): Source table namefilePath(required): Workspace-relative output path (absolute paths and..traversal are rejected unlessHELA_GENOME_ALLOW_EXTERNAL_PATHS=true)format(optional): Output format ("csv" or "json")conditions(optional): WHERE conditions to filter exportoptions(optional): Export options (delimiter, includeHeader)database(optional):"project"or"central", default"project"
Memory and Guidance Tools
Use memory_edit for entity/relation/observation mutations and harness_sessions with action: "list" or "sync" for harness ingestion. Older entry points documented below are compatibility aliases, not additional advertised tools.
initialize_memory - Initialize Memory System
Set up the project memory database schema and tables.
Parameters: None
create_entity - Create Project Entities
Create entities in the project knowledge graph (supports single or batch).
Parameters:
entities(required): Array of entity objectsname: Entity nameentityType: Type (project, task, person, resource)observations: Array of notes about the entity
create_relation - Create Entity Relationships
Create relationships between project entities (supports single or batch).
Parameters:
relations(required): Array of relation objectsfrom: Source entity nameto: Target entity namerelationType: Relationship type (depends_on, blocks, owns, etc.)
add_observation - Add Entity Observations
Add observations/notes to project entities (supports single or batch).
Parameters:
observations(required): Array of observation objectsentityName: Target entity namecontents: Array of observation strings to add
delete_entity - Delete Project Entities
Remove entities and their relations from project memory (supports single or batch).
Parameters:
entityNames(required): Array of entity names to delete
delete_observation - Remove Entity Observations
Remove specific observations from entities (supports single or batch).
Parameters:
deletions(required): Array of deletion objectsentityName: Target entity nameobservations: Array of observation strings to remove
delete_relation - Delete Entity Relationships
Remove relationships between project entities (supports single or batch).
Parameters:
relations(required): Array of relation objects to deletefrom: Source entity nameto: Target entity namerelationType: Relationship type to delete
read_graph - Read Project Knowledge Graph
Retrieve the full knowledge graph, merging the active project database with the central aggregate. Project entries win over central entries with the same name. Supports pagination.
Parameters:
database(optional):"project"(default, merged),"central"(only central)limit(optional, 1-10000, default 5000): Max entities/relations to return,ORDER BY updated_at DESCoffset(optional, 0+): Rows to skip
search_nodes - Search Project Knowledge (Hybrid RAG & Progressive Disclosure)
Search for entities and relations matching a query across names, types, and content, using SQLite FTS5 (BM25) and local vector embeddings with Reciprocal Rank Fusion (RRF $k=60$). Supports progressive disclosure to prevent token bloat.
Parameters:
query(required): Search termlimit(optional, 1-100, default 20): Max ranked entities to returnmode(optional):"keyword"(FTS5 BM25, default),"vector"(sqlite-vec384d), or"hybrid"(RRF fusion)detailLevel(optional): Progressive disclosure level:"compact": Returns lightweight IDs, entity types, observation counts, and 1-line previews (~50 tokens each)."summary": Returns last 2 truncated observations."full": Full entity graph with all observations (default).
open_node - Get Entity Details
Retrieve complete information and all observations about specific project entities (Tier 3 deep recall).
Parameters:
names(required): Array of entity names to retrieve
get_file_context - Fast File History & Context Lookup
Pre-flight check before editing or reading a file. Retrieves prior modification observations, linked features/tasks (implements), and linked blockers/bugs (affects / blocks).
Parameters:
filePath(required): Workspace-relative or absolute file path (e.g."src/auth/jwt.ts")
get_timeline - Chronological Activity Feed
Returns a chronological stream of project observations and events sorted newest first.
Parameters:
since(optional): ISO date string or timestamp filterentityType(optional): Filter by entity type (task, bug, file, decision, project)limit(optional, 1-100, default 20): Max events to return
list_harness_stores - List Harness Session Stores
List local agent-harness session stores (opencode, kilocode, zed, delta, antigravity, cursor, vscode, codex): paths, presence, and format notes. Read-only.
Parameters: None
sync_harness_sessions - Sync Harness Sessions Into Memory
Read-only sync of harness sessions (titles, summaries, timestamps; secrets redacted) into the knowledge graph as session entities named harness:<harness>:<sessionId>. Incremental via watermarks.
Parameters:
harnesses(optional): Subset to sync (default: all found)project(optional): Substring filter on session project/directorysince(optional): Only sessions updated after this ms epochlimit(optional, 1-500, default 50): Max sessions per harnessdryRun(optional): Report what would sync without writingincludeArchived(optional): Include archived sessions (default false)
get_project_guidance - Access AI Guidance
Invoke a project guidance framework to receive specialized instructions and checklists for specific workflows. This allows the AI to autonomously fetch and follow established project management protocols.
Parameters:
guidance_name(required): Name of the guidance (e.g., project-setup, sprint-planning)arguments(optional): Arguments required by the specific guidance framework
Fleet Mission Ledger Tools (3 tools)
Coordinate agents through a SQLite-backed mission board. Claims are exclusive across connections and processes using the same SQLite database. Agents on different machines must call the same server/ledger endpoint to coordinate; separate local databases, central graph synchronization, and vault synchronization do not provide a distributed lock or replicate missions.
create_mission
Enqueue a mission into the fleet mission ledger. Supports assigning to specific agent targets (frea, mema, orchestrator, human, or any), priorities (low, normal, high, urgent), and arbitrary JSON payloads.
Parameters:
title(required): Summary or title of the missiondescription(optional): Detailed context or instructionsoriginAgent(optional, default:agent): Originating agent or usertargetAgent(optional, default:any): Target agent assigned to executepriority(optional, default:normal):low|normal|high|urgentpayload(optional): Input parameters or datadatabase(optional, default:project):project|central
list_missions
Query missions from the ledger filtered by status, agent target, origin, or claiming agent.
Parameters:
id(optional): Specific mission ID to fetchstatus(optional):queued|claimed|in_progress|completed|failed|cancelledtargetAgent(optional): Filter by target agentoriginAgent(optional): Filter by origin agentclaimedBy(optional): Filter by agent currently executinglimit(optional, default: 50, max: 200): Pagination limitoffset(optional, default: 0): Pagination offsetdatabase(optional, default:project):project|central
update_mission
Claim a queued, unowned mission or report its lifecycle progress (e.g. marking completed with output results, or failed with an error message). Automatically records timestamps (claimed_at, completed_at, updated_at). A claim uses one conditional SQL update; competing claimants receive an error rather than replacing the winner.
Parameters:
id(required): Mission ID to updatestatus(optional): New statusclaimedBy(optional): Non-empty agent name, up to 100 characters. Supplying it attempts an exclusive claim, optionally withstatus: claimedorstatus: in_progress. Do not repeat it on subsequent lifecycle updates; claimant reassignment and claimant-freestatus: claimedare rejected.result(optional): JSON result or return value upon completionerror(optional): Error message if mission faileddatabase(optional, default:project):project|central
Runtime Companion Tools
The canonical wrappers are security_scan and cache. The scan_* and cache_* entry points below are legacy aliases; use the action-based wrappers in new integrations.
sync_central_memory
Merge the active project knowledge graph into the central memory database (~/memory/memory.db by default, override with GUARDIAN_CENTRAL_DB). Observation unions preserve independent facts and their existing order; entity type follows the newer timestamp, and relations are unique by endpoints/type. Central imports use the same additive merge instead of overwriting local observations. Every memory write also syncs automatically; call this tool to force a sync on demand. The first sync of each day also snapshots the central database and prunes old backups beyond the newest seven. Central memory remains an aggregate, not a deletion-propagating replica or a mission ledger synchronizer.
set_project_root
Switch the active project memory database to the given absolute project path. Use this at session start when the server was launched outside the project directory, so memory is written to the project instead of the shared fallback database.
path(required): Absolute path to the project root. Inside a Git repository, the toplevel is used.
setup_pre_commit
Create a .pre-commit-config.yaml in the active project root and install the Git hooks, on demand. Requires pre-commit to be installed. The generated .gitignore entries are intentionally broad: alongside memory.db, the block ignores common local tool directories such as .claude/, .vscode/, .idea/, .gemini/, and .cursor/, plus .env files. Entries already present in .gitignore are never duplicated. The server never does any of this automatically at startup.
get_session_context
Summarize active tasks, open bugs, recent changes, blockers, and the next suggested action directly from the knowledge graph.
limit(optional, 1-50, default 10): Maximum entries per result group.
analyze_git_changes
Return exact machine-readable changed paths from Git, including renames and optionally untracked files.
commit(optional): Analyze one commit against its parent.since(optional, default1): Analyze changes since N commits ago or a Git date.includeUntracked(optional, defaulttrue): Include untracked files for worktree analysis.maxFiles(optional, 1-500, default 100): Bound returned paths.commitand a customsincevalue are mutually exclusive.
inspect_untrusted_text
Normalize up to 256 KiB of untrusted text and detect hidden formatting, instruction overrides, role mimicry, hidden HTML/CSS, remote exfiltration markup, and encoded instruction-like content.
text(required): External or otherwise untrusted content.Detection is heuristic. Returned normalized text remains untrusted data.
scan_project_secrets
Scan a workspace-relative file or directory for likely hardcoded credentials. Results contain only type, relative file path, and line number; matched values are never returned.
path(optional, default.): Workspace-relative scan target.exclude(optional): Additional directory names to skip.maxFindings(optional, 1-500, default 100): Bound findings.Absolute paths, traversal, missing paths, and symlink escapes are rejected.
scan_container_image
Run a timeout-limited Trivy scan and return bounded HIGH/CRITICAL vulnerability summaries.
image(required): Container image reference.maxFindings(optional, 1-500, default 100): Bound findings.Requires Trivy. Image values beginning with
-, containing whitespace, or containing control characters are rejected.
Redis cache tools
cache_get: Read onemema:<category>:<name>key.cache_set: Store a value up to 512 KiB with optionalttlSecondsfrom 1 to 604800.cache_delete: Delete one namespaced key.cache_scan: Cursor-scan amema:*pattern with a bounded count.
Project scan paths are restricted to the current Git workspace. Redis tools connect lazily and return an unavailable error when REDIS_URL is unset. Container scanning remains unavailable until Trivy is installed. Read project-guardian://companions/catalog for current capability health.
Obsidian Vault Mirror (optional, remote-capable, agent-controllable)
Set HELA_GENOME_OBSIDIAN_VAULT=/path/to/vault to enable the optional Markdown mirror. SQLite remains the base engine; no Obsidian service is required. Startup imports managed entity and relation notes without clearing SQLite. Only bullets in ## Observations are facts; generated ## Relations backlinks are never imported as observations. Repeated imports are idempotent and retain junk/test-memory guards.
MCP tool: obsidian_vault supports status, sync, rebuild, backfill, sync_central, sync_from_central, and dedup. Rebuild imports notes, not a live database-file replacement. Local deduplication preserves edges/provenance and remembers aliases so central imports do not recreate merged names.
The watcher polls every two seconds and serializes imports. Human observation changes replace the rendered baseline only if SQLite still matches it; divergent agent/human edits merge their observations. Previous note revisions are retained under .hela-conflicts/. Hidden directories are excluded from imports. Deletions are inferred only for notes previously observed by that running watcher, using frontmatter identity; a missing or unreadable vault fails closed. Absence on startup is not a deletion instruction. Central memory is additive: a later explicit central import may restore a project-deleted entity.
Replicated notes retain the earliest creation date and latest update date instead of rewriting remote timestamps to local ones. A replicated observation superset can retain its incoming order without dropping database-only facts. Relation links use a canonical order independent of database insertion order. These rules prevent timestamp/order-only sync loops; genuinely divergent notes still require a deliberate resolution.
Conflict-aware synchronization between machines
Build with npm run build, then configure both legacy hook names to the same two-way transport. The pull hook runs asynchronously at startup and before explicit sync; the write hook is debounced and serialized. Hook failures reach explicit callers; background failures are logged without printing command contents. Legacy rsync --delete hooks are rejected.
export HELA_GENOME_OBSIDIAN_VAULT=/path/to/local/vault
export HELA_GENOME_OBSIDIAN_PULL_CMD="node /path/to/project-mcp/dist/vault-sync.js --vault /path/to/local/vault --peer /path/to/remote/vault --remote user@host"
export HELA_GENOME_OBSIDIAN_SYNC_CMD="$HELA_GENOME_OBSIDIAN_PULL_CMD"Both directories must already exist. The peer requires SSH access and Node.js, but not an installed Genome server or helper. Omit --remote to test two local vault directories.
First sync unions missing files; it never treats initial absence as deletion.
A shared hash baseline permits one-sided edits and deletions only when the other side is unchanged. Divergent edits and edit/delete conflicts leave both canonical states untouched and archive both available revisions plus deletion intent in
.hela-sync/conflicts/on both machines.Overwritten or deleted revisions are retained in
.hela-sync/recovery/. Archives contain.bincontent plus JSON path/hash records. Resolve conflicts by copying the chosen/merged content to both canonical paths, or deleting both copies, then rerun sync.Programmatic repairs can opt into
syncVaults(..., { resolveConflict }). Return aBuffercontaining reviewed merged content, orundefinedto leave the conflict unresolved. Both originals are archived before publication.beforeApply(result)runs under both locks and can reject the complete copy/delete/conflict plan before canonical files change. The CLI does not enable a resolution policy automatically.Exit codes:
0synchronized,2unresolved conflicts,1failed/unavailable. Missing peers, corrupt metadata, and failed SSH commands are not empty snapshots.Locks serialize cooperating synchronizers; expected-hash checks reject stale snapshots. Editors do not honor these locks, so do not treat this as a distributed filesystem transaction. Interrupted or mismatched baselines fall back to conservative reconciliation. Recovery archives preserve replaced data.
Non-hidden regular files, including attachments, are managed;
.obsidian/,.hela-sync/, and other hidden paths are excluded. Symlinks, hardlinks, overlapping local roots, and oversized snapshots are rejected. Default transport limit is 32 MiB per operation with a conservative snapshot budget; the exported API accepts up to 64 MiB.Keep each vault's
.hela-sync/idand state local; do not clone these metadata files between peers. A stale.hela-sync/lockfails closed. Remove only that specific lock after confirming its owning sync process is no longer running; do not erase the baseline to force a deletion.
Run npm test -- --runInBand for isolated coverage. node scripts/test-vault-sync-ssh.mjs user@host checks create/edit/delete conflicts and recovery using disposable directories on both hosts; it never uses the configured production vault.
SQLite backup and isolated restore
SQLiteManager.backupDatabase(database, backupPath) uses SQLite's online backup API, includes committed WAL data, verifies the SQLite header and PRAGMA integrity_check, and publishes a closed snapshot atomically without overwriting an existing destination. Daily central backups and legacy migration use this implementation.
SQLiteManager.restoreDatabase(backupPath, newDatabaseNameOrAbsolutePath) restores only to a new destination after validation. Existing database files, active connections, aliases to existing targets, and SQLite sidecars are refused. A successful isolated restore is evidence that the backup is readable; it is not authorization to overwrite production storage.
For production recovery: stop every writer, take a fresh recovery backup, restore under a new name, verify integrity and expected records, then explicitly switch the service configuration to that restored database. Retain the old database and its WAL/SHM as a coordinated offline recovery set. Never copy over an active SQLite database or delete its sidecars to force a restore.
AI Guidance System
Project Guardian MCP includes comprehensive resources and prompts to help AI models effectively use the toolset for project management.
Available Resources
Project Guardian provides 11 key resources that AI models can read to understand project management concepts, access capability health, and get comprehensive project insights:
project-guardian://templates/entity-types
Standard entity types for project management with examples and usage guidelines.
project-guardian://templates/relationship-types
Common relationship types between project entities with practical examples.
project-guardian://templates/project-workflows
Standard workflows for using Project Guardian tools in different scenarios.
project-guardian://templates/best-practices
Comprehensive best practices guide for effective project knowledge management.
project-guardian://status/current-graph
Current state of the project knowledge graph with summary statistics.
project-guardian://cache/recent-activities
Recently performed project management activities and updates for tracking progress.
project-guardian://cache/workflow-templates
Frequently used workflow templates with examples and implementation guidance.
project-guardian://metrics/project-stats
Statistical overview of project entities, relationships, and activities with health metrics.
project-guardian://cache/team-members
Cached information about project team members and their roles within the organization.
project-guardian://status/recent-changes
Recent additions, updates, and modifications to the knowledge graph for audit and monitoring.
project-guardian://companions/catalog
Lists all six companions, their MCP tools, external prerequisites, and current availability.
Available Prompts
Project Guardian offers 27 prompts covering project setup, planning, quality, operations, and incident workflows:
Core Project Management
project-setup - Project Initialization
Arguments:
project_name(required): Name of the projectteam_members(optional): Comma-separated list of team members
Provides step-by-step guidance for setting up a new project structure with appropriate entities and relationships.
sprint-planning - Sprint Planning
Arguments:
sprint_name(required): Name/number of the sprintduration_days(optional): Sprint duration in days
Guides through comprehensive sprint planning including task breakdown, dependencies, and capacity planning.
progress-update - Progress Tracking
Arguments:
task_name(required): Name of the task to updateprogress_notes(required): Progress update description
Structured process for updating task progress and managing dependencies.
retrospective - Project Retrospective
Arguments:
time_period(required): Time period being reviewed (e.g., "last sprint", "Q1")
Comprehensive retrospective process including data analysis, pattern identification, and improvement action creation.
Quality & Process Management
code-review - Code Review Process
Arguments:
pull_request_title(required): Title of the pull request being reviewedreviewer_name(optional): Name of the reviewer
Structured code review process with technical checklists, issue documentation, and approval workflows.
bug-tracking - Bug Management
Arguments:
bug_description(required): Description of the bug or issueseverity_level(optional): Critical, High, Medium, or Low severity
Complete bug tracking workflow from discovery to resolution with impact analysis and stakeholder communication.
technical-debt-assessment - Technical Debt Analysis
Arguments:
component_name(required): Name of the component or codebase being assessedassessment_scope(optional): Scope of assessment (file, module, system)
Comprehensive technical debt identification, prioritization, and remediation planning.
Release & Deployment Management
release-planning - Release Planning
Arguments:
release_version(required): Version number for the release (e.g., "v2.1.0")release_date(optional): Target release date
Complete release planning process including quality gates, risk assessment, and deployment coordination.
Risk & Change Management
risk-assessment - Risk Management
Arguments:
risk_description(required): Description of the riskimpact_level(optional): High, Medium, or Low impact
Complete workflow for documenting risks, identifying impacts, and developing mitigation strategies.
change-management - Change Control
Arguments:
change_description(required): Description of the proposed changeimpact_assessment(optional): High, Medium, or Low impact assessment
Structured change management process with impact analysis, approval workflows, and implementation tracking.
Team & Resource Management
team-productivity - Productivity Analysis
Arguments:
timeframe(required): Time period to analyze (week, month, quarter)focus_area(optional): Area to focus on (velocity, quality, collaboration)
Team productivity assessment with performance metrics, root cause analysis, and improvement planning.
resource-allocation - Resource Planning
Arguments:
resource_type(required): Type of resource (human, infrastructure, budget)planning_horizon(optional): Planning timeframe (sprint, quarter, year)
Resource allocation optimization with capacity planning, gap analysis, and utilization tracking.
Documentation & Communication
stakeholder-communication - Communication Management
Arguments:
communication_type(required): Type of communication (status_update, issue_alert, milestone_reached)audience(optional): Target audience (team, management, client, all)
Stakeholder communication planning and execution with audience-specific strategies and effectiveness tracking.
documentation-management - Documentation Updates
Arguments:
documentation_type(required): Type of documentation (api, user_guide, technical_spec)update_reason(optional): Reason for documentation update
Documentation maintenance process with content planning, review workflows, and publishing coordination.
Requirements & Planning Management
requirements-gathering - Requirements Gathering
Arguments:
requirement_type(required): Type of requirements (functional, non-functional, business, technical)stakeholders(optional): Comma-separated list of key stakeholders
Guides through comprehensive requirements gathering process with stakeholder management and requirement categorization.
user-story-management - User Story Management
Arguments:
feature_name(required): Name of the feature or epicuser_role(optional): Primary user role (e.g., "customer", "admin", "developer")
Structured process for creating, managing, and prioritizing user stories with acceptance criteria and dependencies.
Quality & Technical Management
testing-strategy - Testing Strategy Development
Arguments:
application_type(required): Type of application (web, mobile, api, desktop)criticality_level(optional): Business criticality (critical, high, medium, low)
Comprehensive testing strategy development including automated testing, quality gates, and risk-based testing.
security-assessment - Security Assessment
Arguments:
assessment_scope(required): Scope of security assessment (application, infrastructure, data)compliance_requirements(optional): Compliance standards (GDPR, HIPAA, SOC2, etc.)
Security assessment framework with vulnerability management, compliance verification, and security controls implementation.
performance-optimization - Performance Optimization
Arguments:
performance_metric(required): Primary metric to optimize (response_time, throughput, resource_usage)optimization_goal(optional): Specific performance target or improvement percentage
Performance monitoring setup, bottleneck identification, and optimization implementation with continuous monitoring.
ci-cd-setup - CI/CD Pipeline Setup
Arguments:
pipeline_type(required): Type of pipeline (build, test, deploy, full_ci_cd)target_platform(optional): Deployment target (aws, azure, gcp, kubernetes, heroku)
Complete CI/CD pipeline setup including quality gates, rollback procedures, and security integration.
architecture-review - Architecture Review
Arguments:
architecture_type(required): Type of architecture (microservices, monolithic, serverless, hybrid)review_focus(optional): Primary focus area (scalability, security, maintainability, performance)
Architectural assessment framework with design pattern analysis, technology stack evaluation, and improvement recommendations.
Knowledge & Team Management
knowledge-transfer - Knowledge Transfer
Arguments:
knowledge_domain(required): Domain of knowledge (technical, process, business)transfer_recipients(optional): Who needs to receive the knowledge (team, individual, department)
Knowledge transfer planning and execution with session management, documentation, and effectiveness validation.
vendor-management - Vendor Management
Arguments:
vendor_type(required): Type of vendor service (cloud, development, consulting, infrastructure)contract_value(optional): Contract value range (small, medium, large, enterprise)
Vendor relationship management including contract tracking, performance monitoring, and cost optimization.
Incident & Crisis Management
incident-response - Incident Response
Arguments:
incident_severity(required): Severity level (critical, high, medium, low)incident_type(optional): Type of incident (security, performance, functionality, availability)
Incident response framework with containment, recovery, root cause analysis, and post-incident review.
Financial & Resource Management
cost-management - Cost Management
Arguments:
cost_category(required): Primary cost category (infrastructure, personnel, tools, licenses)budget_constraint(optional): Budget constraint level (strict, flexible, unlimited)
Cost monitoring, optimization strategies, and budget management with forecasting and reporting.
Customer & Innovation Management
customer-feedback - Customer Feedback Management
Arguments:
feedback_channel(required): Primary feedback channel (survey, support, reviews, analytics)feedback_focus(optional): Focus area (usability, features, performance, support)
Customer feedback collection, analysis, and action planning with continuous improvement cycles.
innovation-planning - Innovation Planning
Arguments:
innovation_type(required): Type of innovation (product, process, technology, business_model)risk_tolerance(optional): Risk tolerance level (conservative, moderate, aggressive)
Innovation management framework with idea generation, experimentation, and success measurement.
How AI Models Use Guidance
Discovery: List available resources and prompts to understand capabilities
Learning: Read relevant resources to understand project management concepts
Planning: Use appropriate prompts for complex workflows
Execution: Follow structured guidance to use tools effectively
Verification: Check results and iterate as needed This guidance system ensures AI models can provide expert-level project management assistance using the Project Guardian toolset.
Behavioral Protocol (System Rules)
Every prompts/get response from this MCP server includes a shared Behavioral Protocol as a system message (implemented in src/prompts/behavioral-protocol.ts). This protocol enforces:
Minimal, production-ready, self-documenting code with a security-first approach.
No buzzwords, unnecessary emoji, or filler; direct, technically accurate answers.
Adaptive response depth based on the user's request (quick answers vs. complex breakdowns).
Consistent use of validated best practices for systems, programming, UI/UX, and design.
Clients integrating this MCP server should treat the first system message as the governing rules for any downstream model that uses these prompts.
Usage Examples

Project Guardian Setup
// Initialize the project memory system
const initResult = await mcpClient.callTool('initialize_memory', {});
// Create your first project entities
const entityResult = await mcpClient.callTool('create_entity', {
entities: [
{
name: 'web_platform',
entityType: 'project',
observations: ['Main web application platform', 'React + Node.js stack', 'Q2 2024 delivery']
},
{
name: 'user_authentication',
entityType: 'feature',
observations: ['OAuth2 implementation', 'Google/GitHub providers', 'JWT tokens']
}
]
});
// Establish project relationships
const relationResult = await mcpClient.callTool('create_relation', {
relations: [
{
from: 'user_authentication',
to: 'web_platform',
relationType: 'part_of'
}
]
});Project Management Workflow
// Add progress observations
await mcpClient.callTool('add_observation', {
observations: [
{
entityName: 'user_authentication',
contents: [
'Completed OAuth2 setup for Google provider',
'JWT implementation finished',
'Unit tests passing at 95% coverage'
]
}
]
});
// Search project knowledge
const searchResult = await mcpClient.callTool('search_nodes', {
query: 'authentication'
});
// Read entire project knowledge graph
const graphResult = await mcpClient.callTool('read_graph', {});
// Get detailed entity information
const entityDetails = await mcpClient.callTool('open_node', {
names: ['user_authentication', 'web_platform']
});Database Operations
// Execute custom SQL queries
const sqlResult = await mcpClient.callTool('execute_sql', {
query: 'SELECT * FROM entities WHERE entity_type = ?',
parameters: ['project']
});
// Query project data
const queryResult = await mcpClient.callTool('query_data', {
table: 'entities',
conditions: { entity_type: 'task' },
limit: 10
});
// Import/export data
const importResult = await mcpClient.callTool('import_data', {
table: 'project_data',
filePath: './project_backup.csv',
format: 'csv'
});Configuration

Environment Variables
The server reads these variables at startup:
Variable | Default | Purpose |
| unset | Absolute path to the project root. When set, |
|
| Absolute path to the central memory database that every project syncs into. Backups are written to a |
| unset | Set to |
| unset | Enables the Redis-backed |
| platform default | Base directory for the shared fallback database outside a Git repository |
| unset = off | Set to |
| unset = off | Set to |
| unset = off | Set to |
| unset = off | Set to |
MCP clients launch servers with their own working directory, which is often your home folder rather than the project you are editing. In that situation Git detection cannot find the project and every session writes to the shared fallback database. Two ways to fix this:
Set
GUARDIAN_PROJECT_ROOTin the project's MCP configuration (see the client examples below).Call the
set_project_roottool with the absolute project path at session start — no configuration edits needed. The switch applies to the running server; set the environment variable if you want it to apply automatically to every future session.
Optional Runtime Services
Redis is optional and is never contacted during startup. Configure it only when cache tools are needed:
{
"env": {
"REDIS_URL": "redis://localhost:6379/0"
}
}Trivy is discovered from PATH when scan_container_image is called. Missing Redis or Trivy affects only its associated tools; memory, database, guidance, session, Git, wall, and project-secret tools remain available.
The companion catalog reports available, optional, or unavailable for each runtime capability. The server uses stdio transport and does not expose an HTTP listener.
For Cursor IDE
Add this server to your Cursor MCP configuration (~/.cursor/mcp.json). Replace the GUARDIAN_PROJECT_ROOT value with the project this configuration belongs to:
{
"mcpServers": {
"project-guardian": {
"command": "node",
"args": ["/path/to/project-mcp/dist/index.js"],
"env": {
"GUARDIAN_PROJECT_ROOT": "/path/to/your/project"
}
}
}
}For Claude Desktop
Add this server to your Claude Desktop configuration (claude_desktop_config.json), following the same pattern:
{
"mcpServers": {
"project-guardian": {
"command": "node",
"args": ["/path/to/project-mcp/dist/index.js"],
"env": {
"GUARDIAN_PROJECT_ROOT": "/path/to/your/project"
}
}
}
}Project Structure
project-mcp/
├── src/
│ ├── index.ts # Main entry point
│ ├── server.ts # MCP server orchestrator
│ ├── memory-manager.ts # Knowledge graph and FTS5 RAG semantic search
│ ├── sqlite-manager.ts # Database operations and connection management
│ ├── import-export.ts # CSV/JSON data import and export functionality
│ ├── obsidian-vault.ts # Optional Obsidian vault mirror (human view)
│ ├── types.ts # TypeScript type definitions and schemas
│ ├── handlers/
│ │ └── request-handlers.ts # Central tool execution dispatcher
│ ├── tools/
│ │ ├── tool-registry.ts # Tool definitions and listing
│ │ ├── database-tools.ts # Database operation tool schemas
│ │ ├── memory-tools.ts # Memory management tool schemas
│ │ ├── guidance-tools.ts # Guidance tool schema
│ │ └── runtime-tools.ts # Companion runtime tool schemas
│ ├── runtime/
│ │ ├── path-guard.ts # Workspace path containment
│ │ └── runtime-capabilities.ts # Native companion implementations
│ ├── resources/
│ │ ├── resource-registry.ts # Resource definitions and handlers
│ │ ├── resource-definitions.ts # Static resource metadata
│ │ ├── resource-handlers.ts # Dynamic resource content generation
│ │ └── companion-catalog.ts # Companion capability health
│ └── prompts/
│ ├── prompt-registry.ts # Prompt definitions and handlers
│ ├── prompt-definitions.ts # Static prompt metadata
│ ├── prompt-handlers.ts # Dynamic prompt content generation
│ └── behavioral-protocol.ts # Shared Behavioral Protocol system prompt
├── (no ui/ directory) # Web UI dashboard removed; Obsidian vault is the human view
│ └── vite.config.ts # Vite build configuration
├── __tests__/ # Comprehensive test suite
│ ├── tool-registry.test.ts
│ ├── resource-registry.test.ts
│ ├── prompt-registry.test.ts
│ ├── request-handlers.test.ts
│ ├── runtime-capabilities.test.ts
│ ├── import-export.test.ts
│ ├── sqlite-manager.test.ts
│ └── bug-fixes.test.ts
├── skills/ # Six distributable guardian-* AgentSkills
├── dist/ # Ignored production build output
├── memory.db # Ignored local SQLite state, created on first run
├── package.json # Project dependencies and scripts
├── package.prod.json # Production-only dependencies for smaller bundle
├── tsconfig.json # TypeScript configuration
├── jest.config.js # Test configuration
└── README.md # This documentationKey Components
server.ts: MCP server lifecycle, transport, handlers, and shutdown coordination
handlers/request-handlers.ts: Central dispatcher routing tool calls to appropriate managers
tools/: Tool definition and registration system (29 canonical tools; legacy action aliases are not additional advertised tools)
tool-registry.ts: Lists all available tools (7 DB + 12 memory + 1 guidance + 12 runtime + 2 session bridge + 4 UI/stream)database-tools.ts: Database operation schemas (7 tools)memory-tools.ts: Memory management schemas (12 tools)session-bridge-tools.ts: Session bridge ingestion schemas (2 tools)guidance-tools.ts: Autonomous guidance tool schema (1 tool)runtime-tools.ts: Typed companion capability schemas (12 tools)
hooks/: Zero-touch lifecycle hooks (
session-start.mjs,post-tool-run.mjs)runtime/: Workspace guards and companion runtime implementations
resources/: Resource management system (11 resources total)
resource-registry.ts: Resource listing and content servingresource-definitions.ts: Static resource metadataresource-handlers.ts: Dynamic content generation
prompts/: Prompt management system (27 prompts total)
prompt-registry.ts: Prompt listing and content servingprompt-definitions.ts: Static prompt metadataprompt-handlers.ts: Dynamic prompt generation with contextbehavioral-protocol.ts: Centralized Behavioral Protocol system message used by all prompts
memory-manager.ts: Knowledge graph operations for entities, relationships, and observations
sqlite-manager.ts: Database abstraction with bounded connection caching and schema management
import-export.ts: CSV, JSON, and SQL data transfer utilities
types.ts: Zod schemas for input validation and TypeScript type safety
skills/: Agent-side workflows, scripts, references, and assets for the six companion packages
Local State
memory.db and its memory.db-* sidecars are runtime state and are ignored by Git. Each project keeps its own database at its resolved project root (see Environment Variables); projects outside any Git repository without an explicit root share the fallback database under $XDG_DATA_HOME/project-guardian. In addition, every memory write mirrors into the central database at ~/memory/memory.db, which is a merge across projects: deleting an entity in one project does not remove it from the central copy, so treat the central database as a searchable aggregate rather than a per-project backup. Daily snapshots live in ~/memory/backup/. A clone starts with no project memory; the server creates the database and schema locally on first run. Back up or export memory explicitly when it must move between machines. Never commit the database because observations can contain private project context.
The database tools (execute_sql, query_data, insert_data, update_data, delete_data, import_data, export_data) accept a database selector: project (default) targets the active project database, central targets the aggregate.
Development
Clone the repository:
git clone https://github.com/Hela-Ecosystem/project-mcp.git
cd project-mcpInstall dependencies:
npm installBuild the project: For active development (with file watching):
npm run devFor a standard build:
npm run buildFor a production-optimized build:
npm run build:prodRun tests:
npm testStart the server:
npm startLicense
GPL-3.0-or-later License - see LICENSE file for details.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Project memory for coding agents: requirements, decisions, code graph and delivery telemetry.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Project memory, documentation and controlled secret access for AI coding agents.
Durable, shareable and governed project memory with smart triage and explicit project composition.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides AI agents with persistent, searchable memory using a knowledge graph stored in SQLite. Features semantic search, temporal awareness, and workflow-aware prompts for development projects.MIT
- AlicenseNot gradedqualityDmaintenanceA persistent memory server for AI agents that stores structured notes in a local SQLite database with full-text search and graph-based relationships. It features 32 specialized tools for managing long-term context, including version history, automated TTL expiration, and complex filtering.12 npmMIT
- AlicenseNot gradedqualityDmaintenanceProvides Claude with a persistent local memory and structured knowledge graph to track project states, tasks, and historical decisions across different chat sessions. It enables users to recall information using keyword relevance, time-travel queries, and dependency analysis for complex project management.MIT
- AlicenseBqualityDmaintenanceUltra-lean memory system for AI coding tools that stores project knowledge locally with SQLite and enables AI to remember your project across sessions.1285 npm37MIT