Skip to main content
Glama
README.md
# Project Guardian MCP

<!-- hela:version:start -->
**MCP server:** `hela-genome` · **Version:** `3.0.6` · **Canonical tools:** 31. [Current tool reference](docs/TOOLS.md).
<!-- hela:version:end -->


> **Part of the [HeLa MCP Ecosystem](https://github.com/Hela-Ecosystem/hela-mcp-ecosystem)** — This server is **HeLa Genome (`hela-genome`)** — the *State & Memory* component of the HeLa cellular architecture. See the [ecosystem docs](https://github.com/Hela-Ecosystem/hela-mcp-ecosystem) 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.

![Blotcat — guardian on duty, wiring the knowledge graph from memory.db](assets/blotcat-hero.jpg)

## Table of Contents

- [Features](#features)
  - [Project Guardian Memory System](#project-guardian-memory-system)
  - [Streamlined Database Operations](#streamlined-database-operations)
  - [Runtime Companion Integration](#runtime-companion-integration)
  - [AI Guidance System](#ai-guidance-system)
  - [Advanced Features](#advanced-features)
  - [Enterprise Features](#enterprise-features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Available Tools](#available-tools)
  - [Database Operations (7 tools)](#database-operations-7-tools)
  - [Memory and Guidance Tools](#memory-and-guidance-tools)
  - [Fleet Mission Ledger Tools (3 tools)](#fleet-mission-ledger-tools-3-tools)
  - [Runtime Companion Tools](#runtime-companion-tools)
- [AI Guidance System](#ai-guidance-system)
  - [Available Resources](#available-resources)
  - [Available Prompts](#available-prompts)
  - [How AI Models Use Guidance](#how-ai-models-use-guidance)
- [Usage Examples](#usage-examples)
  - [Project Guardian Setup](#project-guardian-setup)
  - [Project Management Workflow](#project-management-workflow)
  - [Database Operations](#database-operations)
- [Configuration](#configuration)
  - [Optional Runtime Services](#optional-runtime-services)
  - [For Cursor IDE](#for-cursor-ide)
  - [For Claude Desktop](#for-claude-desktop)
- [Project Structure](#project-structure)
- [Development](#development)
- [License](#license)

## Features

### Project Guardian Memory System

![Blotcat pouring a small project memory bucket into a large central memory vat](assets/blotcat-memory-sync.jpg)
- **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 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.db` migration uses the same snapshot procedure and retains the original for recovery.
- **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

![Blotcat efficiently sorting raw data blocks on a conveyor belt into the structured memory.db SQLite wall](assets/blotcat-db-ops.jpg)
- **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
- **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 (including `obsidian_vault`). 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

![Blotcat acting as a conductor for miniature sub-Blotcats acting as security, memory, and tracker companions](assets/blotcat-companions.jpg)

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 | `memory_edit`, graph/search/context 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 | `security_scan` (`secrets` / `container`) |
| `guardian-cache` | Optional namespaced Redis storage | `cache` (`get` / `set` / `delete` / `scan`) |

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

![Blotcat as an academic master pointing at a glowing scroll of strict rules and project prompts](assets/blotcat-ai-guidance.jpg)
- **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 `SELECT` results are bounded; use the MCP `read_graph`, `read_graph_stream`, and `search_nodes` schemas 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 lint` checks 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.json` for the package's declared standalone engine range.
- **npm**: Latest stable version
- **SQLite3**: Automatically installed as dependency
- **Redis**: Optional; required only for `cache` actions through `REDIS_URL`
- **Trivy**: Optional; required only for `security_scan` with `action: "container"`

## Installation

1. **Clone the repository:**
```bash
git clone https://github.com/Hela-Ecosystem/project-mcp.git
cd project-mcp
```

2. **Install dependencies:**
```bash
npm install
```

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

For development (includes source maps and full TypeScript compilation):
```bash
npm run build
```

For production (creates an optimized, minified bundle):
```bash
npm run build:prod
```

4. **Run the test suite:**
```bash
npm test
```

5. **Start the server:**
```bash
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

![Blotcat opening a large toolbox with three labeled drawers, holding a wrench](assets/blotcat-tool-categories.jpg)

This MCP server currently advertises **29 canonical tools**. The generated [tool reference](docs/TOOLS.md) 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_vault` and 3 fleet mission tools `create_mission`, `list_missions`, `update_mission`; removed `ui_server` in favor of the Obsidian vault mirror). Legacy names such as `create_entity` and `cache_get` normalize 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 string
- `parameters` (optional): Query parameters array
- `database` (optional): `"project"` or `"central"`, default `"project"`

#### `query_data` - Query Table Data
Query memory tables with filtering and pagination.

**Parameters:**
- `table` (required): Table name
- `conditions` (optional): WHERE conditions object
- `limit` (optional): Maximum rows to return
- `offset` (optional): Number of rows to skip
- `orderBy` (optional): Column to sort by
- `orderDirection` (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 name
- `records` (required): Array of record objects to insert
- `database` (optional): `"project"` or `"central"`, default `"project"`

#### `update_data` - Update Records
Update records in a memory table.

**Parameters:**
- `table` (required): Table name
- `conditions` (required): WHERE conditions for records to update
- `updates` (required): Fields to update
- `database` (optional): `"project"` or `"central"`, default `"project"`

#### `delete_data` - Delete Records
Delete records from a memory table.

**Parameters:**
- `table` (required): Table name
- `conditions` (required): WHERE conditions for records to delete
- `database` (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 name
- `filePath` (required): Workspace-relative path to the source file (absolute paths and `..` traversal are rejected unless `HELA_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 name
- `filePath` (required): Workspace-relative output path (absolute paths and `..` traversal are rejected unless `HELA_GENOME_ALLOW_EXTERNAL_PATHS=true`)
- `format` (optional): Output format ("csv" or "json")
- `conditions` (optional): WHERE conditions to filter export
- `options` (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 objects
  - `name`: Entity name
  - `entityType`: 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 objects
  - `from`: Source entity name
  - `to`: Target entity name
  - `relationType`: 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 objects
  - `entityName`: Target entity name
  - `contents`: 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 objects
  - `entityName`: Target entity name
  - `observations`: 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 delete
  - `from`: Source entity name
  - `to`: Target entity name
  - `relationType`: 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 DESC`
- `offset` (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 term
- `limit` (optional, 1-100, default 20): Max ranked entities to return
- `mode` (optional): `"keyword"` (FTS5 BM25, default), `"vector"` (`sqlite-vec` 384d), 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 filter
- `entityType` (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/directory
- `since` (optional): Only sessions updated after this ms epoch
- `limit` (optional, 1-500, default 50): Max sessions per harness
- `dryRun` (optional): Report what would sync without writing
- `includeArchived` (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 mission
- `description` (optional): Detailed context or instructions
- `originAgent` (optional, default: `agent`): Originating agent or user
- `targetAgent` (optional, default: `any`): Target agent assigned to execute
- `priority` (optional, default: `normal`): `low` | `normal` | `high` | `urgent`
- `payload` (optional): Input parameters or data
- `database` (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 fetch
- `status` (optional): `queued` | `claimed` | `in_progress` | `completed` | `failed` | `cancelled`
- `targetAgent` (optional): Filter by target agent
- `originAgent` (optional): Filter by origin agent
- `claimedBy` (optional): Filter by agent currently executing
- `limit` (optional, default: 50, max: 200): Pagination limit
- `offset` (optional, default: 0): Pagination offset
- `database` (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 update
- `status` (optional): New status
- `claimedBy` (optional): Non-empty agent name, up to 100 characters. Supplying it attempts an exclusive claim, optionally with `status: claimed` or `status: in_progress`. Do not repeat it on subsequent lifecycle updates; claimant reassignment and claimant-free `status: claimed` are rejected.
- `result` (optional): JSON result or return value upon completion
- `error` (optional): Error message if mission failed
- `database` (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, default `1`): Analyze changes since N commits ago or a Git date.
- `includeUntracked` (optional, default `true`): Include untracked files for worktree analysis.
- `maxFiles` (optional, 1-500, default 100): Bound returned paths.
- `commit` and a custom `since` value 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 one `mema:<category>:<name>` key.
- `cache_set`: Store a value up to 512 KiB with optional `ttlSeconds` from 1 to 604800.
- `cache_delete`: Delete one namespaced key.
- `cache_scan`: Cursor-scan a `mema:*` 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.

```bash
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 `.bin` content 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 a `Buffer` containing reviewed merged content, or `undefined` to 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: `0` synchronized, `2` unresolved conflicts, `1` failed/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/id` and state local; do not clone these metadata files between peers. A stale `.hela-sync/lock` fails 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 project
- `team_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 sprint
- `duration_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 update
- `progress_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 reviewed
- `reviewer_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 issue
- `severity_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 assessed
- `assessment_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 risk
- `impact_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 change
- `impact_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 epic
- `user_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

1. **Discovery**: List available resources and prompts to understand capabilities
2. **Learning**: Read relevant resources to understand project management concepts
3. **Planning**: Use appropriate prompts for complex workflows
4. **Execution**: Follow structured guidance to use tools effectively
5. **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

![Blotcat routing prompts and tools into memory.db](assets/blotcat-workflow.jpg)

### Project Guardian Setup

```typescript
// 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

```typescript
// 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

```typescript
// 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

![Blotcat plugging a giant power cord into a wall socket](assets/blotcat-configuration.jpg)

### Environment Variables

The server reads these variables at startup:

| Variable | Default | Purpose |
| --- | --- | --- |
| `GUARDIAN_PROJECT_ROOT` | unset | Absolute path to the project root. When set, `memory.db` is stored here instead of relying on Git detection |
| `GUARDIAN_CENTRAL_DB` | `~/memory/memory.db` | Absolute path to the central memory database that every project syncs into. Backups are written to a `backup/` directory next to it |
| `GUARDIAN_AUTO_MERGE` | unset | Set to `1` to enable scattered-database consolidation at startup. This merges nested `memory.db` files into the project-root database and deletes them, so leave it unset when sub-projects keep separate memories |
| `REDIS_URL` | unset | Enables the Redis-backed `cache_*` tools |
| `XDG_DATA_HOME` | platform default | Base directory for the shared fallback database outside a Git repository |
| `HELA_GENOME_ALLOW_SQL_WRITE` | *unset = off* | Set to `true` to allow `execute_sql` writes. Read-only `SELECT`/`WITH`/`VALUES`/`EXPLAIN` and whitelisted `PRAGMA` reads always allowed. |
| `HELA_GENOME_ALLOW_DESTRUCTIVE` | *unset = off* | Set to `true` to allow `delete_data` and `setup_pre_commit` (Git hook install). |
| `HELA_GENOME_ALLOW_EXTERNAL_PATHS` | *unset = off* | Set to `true` to let `import_data`/`export_data` use absolute or traversal paths outside the active project root. Off = paths must stay inside the workspace. |
| `HELA_ENVELOPE` | *unset = off* | Set to `true` to wrap tool results in the canonical HeLaResult envelope (`ok/summary/data/artifacts/provenance/warnings/sideEffects/execution`). Off = byte-identical legacy output. Run/step ids propagate from `HELA_RUN_ID`/`HELA_STEP_ID`. |

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:

1. Set `GUARDIAN_PROJECT_ROOT` in the project's MCP configuration (see the client examples below).
2. Call the `set_project_root` tool 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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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 documentation
```

### Key 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 serving
  - `resource-definitions.ts`: Static resource metadata
  - `resource-handlers.ts`: Dynamic content generation
- **prompts/**: Prompt management system (27 prompts total)
  - `prompt-registry.ts`: Prompt listing and content serving
  - `prompt-definitions.ts`: Static prompt metadata
  - `prompt-handlers.ts`: Dynamic prompt generation with context
  - `behavioral-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](#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

1. **Clone the repository:**
```bash
git clone https://github.com/Hela-Ecosystem/project-mcp.git
cd project-mcp
```

2. **Install dependencies:**
```bash
npm install
```

3. **Build the project:**
For active development (with file watching):
```bash
npm run dev
```

For a standard build:
```bash
npm run build
```

For a production-optimized build:
```bash
npm run build:prod
```

4. **Run tests:**
```bash
npm test
```

5. **Start the server:**
```bash
npm start
```

## License

GPL-3.0-or-later License - see LICENSE file for details.