ProjectMind

ProjectMind is a local-first, privacy-preserving project intelligence and persistent context engine that enables AI coding agents to understand, remember, and work with software repositories without repeatedly scanning the entire codebase.

ProjectMind is not a separate chatbot or code editor. It is an autonomous intelligence and persistent memory layer used directly by your existing coding agents: Google Antigravity, Anthropic Claude Code, Cursor, Google Gemini CLI, OpenAI Codex, GitHub Copilot in VS Code, OpenCode, Hermes Agent, and DeepSeek Harness / Hermes.

Table of Contents

• Quick Start

• Prerequisites & System Requirements

• Installation Guide

  • Option A: One-Line Remote Installer (curl | bash)

  • Option B: Local Repository Installation

  • Windows Installation (PowerShell)

• First Command After Installation

• Essential CLI Commands

• Troubleshooting & Diagnostics

  • Resolving @projectmind/shared / Missing Workspace Links

  • Running Health Diagnostics

  • Common Issues & Solutions

• Architecture & Visual Overview

  • System Architecture

  • 3-Layer Persistent Memory Architecture

  • Smart Auto Mode Lifecycle Workflow

  • Universal Agent Integration Matrix

• CLI Visual Walkthrough

• Agent Compatibility Matrix

• Key Capabilities

• The 27 MCP Intelligence Tools

• What's New in v1.1.0

• Monorepo Build & Test

• Documentation Guides

• License

Related MCP server: DIP

Quick Start

Get ProjectMind running on your system in under 60 seconds:

# 1. Install ProjectMind via the official installer
curl -fsSL https://raw.githubusercontent.com/Rootx202/ProjectMind/main/install.sh | bash

# 2. Ensure ~/.local/bin is in your PATH (if not already added)
export PATH="$HOME/.local/bin:$PATH"

# 3. Verify installation and inspect detected coding agents
projectmind plugin doctor

# 4. Install integration for your preferred agent (or install all 9 supported agents)
projectmind plugin install --all

Once installed, open any project in your coding agent (e.g. Antigravity, Claude Code, Cursor, Gemini CLI) and work normally. Smart Auto Mode automatically initializes project memory on first encounter, retrieves selective task-scoped context before coding, and synchronizes modified files after edits without requiring manual commands.

Prerequisites & System Requirements

ProjectMind operates entirely on your local machine with zero external cloud dependencies.

Installation Guide

ProjectMind supports two primary installation methods on Linux & macOS, plus a dedicated Windows PowerShell installer.

Option A: One-Line Remote Installer (curl | bash)

Best for users who want to install the ProjectMind CLI and agent integrations directly without cloning or managing the monorepo source:

curl -fsSL https://raw.githubusercontent.com/Rootx202/ProjectMind/main/install.sh | bash

How it works:

1. Runs safely via pipe without BASH_SOURCE unbound variable errors.

2. Installs runtime files into ~/.projectmind (or custom $PROJECTMIND_HOME).

3. Generates the executable wrapper in ~/.local/bin/projectmind.

4. Executes diagnostic verification (projectmind plugin doctor) before declaring success. If diagnostics fail, the installer exits with a non-zero code and reports the error immediately.

Customizing remote installation:

# Install integration for a specific agent directly
curl -fsSL https://raw.githubusercontent.com/Rootx202/ProjectMind/main/install.sh | bash -s -- --agent antigravity

# Install all 9 agent integrations during setup
curl -fsSL https://raw.githubusercontent.com/Rootx202/ProjectMind/main/install.sh | bash -s -- --all

# Custom installation directory
curl -fsSL https://raw.githubusercontent.com/Rootx202/ProjectMind/main/install.sh | bash -s -- --prefix /opt/projectmind --bin-dir /usr/local/bin

Option B: Local Repository Installation

Best for contributors, developers modifying ProjectMind, or air-gapped environments:

# 1. Clone the repository
git clone https://github.com/Rootx202/ProjectMind.git
cd ProjectMind

# 2. Run the local installer
./install.sh

How it works:

1. Automatically detects that it is executing inside a local repository checkout.

2. Installs dependencies and links all internal @projectmind/* packages via npm workspaces.

3. Compiles TypeScript sources to JavaScript (dist/) and verifies all 13 internal packages are resolvable.

4. Creates a symlink wrapper ~/.local/bin/projectmind pointing directly to apps/cli/dist/index.js.

5. Runs projectmind plugin doctor to verify environment health.

Options for local installer:

# Install integrations for all 9 agents
./install.sh --all

# Install integration for a single agent
./install.sh --agent claude-code

# Perform dry-run without writing files
./install.sh --dry-run

Windows Installation (PowerShell)

For Windows 10, Windows 11, or Windows Server:

# In PowerShell (run as regular user or Administrator):
.\install.ps1

# Or specify a target agent:
.\install.ps1 -Agent antigravity -All

The Windows installer automatically resolves directory boundaries, adds %USERPROFILE%\.local\bin to user PATH, and configures agent MCP settings with Windows path separators. See WINDOWS.md for detailed Windows instructions.

First Command After Installation

Immediately after installation, verify your environment and check agent integration health:

# 1. Verify system environment, Node.js version, and agent detection
projectmind plugin doctor

Sample output:

✓ Node.js Runtime: v20.19.5 (>= 18.0.0 supported)
✓ Filesystem Storage: ~/.projectmind (read/write verified)
✓ SQLite Engine: SQLite 3.46.1 with FTS5 virtual table support
✓ Workspace Linkage: All 13 internal @projectmind/* packages resolvable
✓ Agent Integrations: 9 supported (Google Antigravity, Claude Code, Cursor, Gemini CLI, etc.)

Next, view all supported coding agent integrations:

projectmind plugin list

To configure ProjectMind inside your current project repository:

cd /path/to/my-project
projectmind init

(Or simply open your project in your coding agent — Smart Auto Mode initializes automatically!)

Essential CLI Commands

ProjectMind provides a unified CLI (projectmind or node apps/cli/dist/index.js):

Troubleshooting & Diagnostics

Resolving @projectmind/shared / Missing Workspace Links

Symptom:

Error: Cannot find module '@projectmind/shared'
or: npm workspace links are missing under node_modules/@projectmind

Root Cause: This issue occurs in local repository checkouts when:

1. npm install was run before workspace definitions were synced, causing npm not to link @projectmind/* packages inside node_modules/@projectmind/.

2. The project was executed before running node scripts/build.js, so package entry points (dist/index.js) were not yet compiled.

Permanent Fix: Run the following two commands from the root of the repository:

# 1. Link all internal workspace packages natively
npm install

# 2. Compile TypeScript sources and verify package resolution
node scripts/build.js

scripts/build.js includes an automated workspace symlink safeguard (ensureWorkspaceLinks()) and a post-build verification step that tests require.resolve() on all 13 @projectmind/* packages. The build will exit with an error code if any internal dependency cannot be resolved.

Running Health Diagnostics

Whenever you encounter unexpected behavior, run the built-in doctor:

projectmind plugin doctor

To run diagnostics for a specific project folder:

projectmind plugin doctor --project-root /path/to/my-project

Common Issues & Solutions

• Agent does not show ProjectMind MCP tools after installation:

  • Solution: Certain agents (such as Anthropic Claude Code, Google Gemini CLI, and OpenAI Codex) load MCP servers at startup. Restart your agent session or run /mcp reload inside the agent.

• Lifecycle hooks do not fire in Cursor or Google Gemini CLI:

  • Solution: Ensure your workspace is marked as Trusted in Cursor or Gemini CLI settings. Untrusted workspaces disable local lifecycle hooks for security reasons.

• Corrupted SQLite Database:

  • Solution: ProjectMind checks database integrity on every startup. If a file is corrupted, ProjectMind automatically moves the corrupted file to .projectmind/backups/corrupted-<timestamp>.db.bak and re-initializes a fresh database without losing Git history.

• Moved Repository Folder:

  • Solution: ProjectMind uses stable cryptographic project identifiers. If you move or rename a repository folder, ProjectMind automatically detects the move, updates projectRoot, and preserves all historical memory.

See TROUBLESHOOTING.md for more in-depth solutions.

Architecture & Visual Overview

ProjectMind's modular architecture decouples high-level AI agent interaction from local persistent storage and selective retrieval.

System Architecture

The 4-tier stack integrates coding agents via native hooks and MCP protocols into a unified core engine backed by local SQLite3 storage:

3-Layer Persistent Memory Architecture

Memory is partitioned into three strictly isolated tiers to ensure ultra-fast bootstrapping, fact verification, and prevent hallucination contamination:

Smart Auto Mode Lifecycle Workflow

Continuous autonomous synchronization runs behind the scenes during normal development sessions without manual user commands:

Universal Agent Integration Matrix

Grounded adapter support for 9 distinct AI coding agent ecosystems across hooks, MCP servers, rules, and skills:

CLI Visual Walkthrough

The following captures demonstrate real terminal executions from ProjectMind running locally:

1. Diagnostics & Environment Health Check (projectmind plugin doctor)

Validates Node.js runtime, filesystem read/write permissions, and inspects detection status across all 9 agent platforms:

2. Multi-Agent Ecosystem Status (projectmind plugin list)

Displays all 9 supported coding agent integrations, installed plugins, detected environments, and adapter capabilities:

3. Selective Context Retrieval & Token Budgeting (projectmind context)

Demonstrates intelligent task scoping, module dependency multi-hop traversal, and token budget allocation (using only 768 tokens of a 4,000 token budget for multi-module tasks):

4. Continuous Update Management (projectmind update check & plugin outdated)

Verifies Core engine updates and individual plugin versions directly against official GitHub Releases with SHA-256 integrity verification:

Agent Compatibility Matrix

All adapter implementations are grounded in official documentation for each coding environment:

Key Capabilities

• Zero-Command Daily Workflow (Smart Auto Mode): Once installed, the agent automatically initializes project memory on first encounter, retrieves selective task-scoped context before coding, and incrementally synchronizes modified files after edits.

• 7-Stage Controlled Bootstrap: Analyzes project metadata, file inventory, entry points, architectural docs, module topology, symbols/routes/models, and SHA-256 fingerprints without blindly reading large or binary files or modifying source code.

• Knowledge Reliability & Provenance: Every record tracks verificationStatus (verified, inferred, planned, unverified, outdated), confidence score, source file references, and SHA-256 fingerprints. Inferences and planned prompt specifications are never presented as verified implementation facts.

• Existing & Greenfield Project Support: Supports indexing existing codebases and initializing brand-new projects from an initial prompt or specification (mode: "prompt"), automatically transitioning records from planned to verified as code is implemented.

• Strict Local-First Security & Privacy: Indexing, retrieval, and memory writes work 100% offline with zero mandatory cloud accounts or paid embedding APIs. Enforces secret exclusion (.env, .pem, .key, .ssh, tokens), path traversal and symlink escape protection, and prompt-injection sanitization.

The 27 MCP Intelligence Tools

ProjectMind exposes 27 structured tools over standard JSON-RPC 2.0 stdio transport:

What's New in v1.1.0

• Resilient Multi-Mode Installer: install.sh supports both piped execution (curl | bash) and local repository installations, with safe variable expansions, robust dependency linking, and non-zero exit codes on diagnostic failures.

• Strict Workspace Linkage: All internal packages declare mutual workspace dependencies, eliminating missing @projectmind/shared errors during offline local builds.

• Snapshot-bound context: Change detection runs before any retrieval cache lookup; caches are keyed by workspace tree hash plus parser/retrieval/embedder versions. Stale context is never returned.

• Verified updates only: Plugin artifacts are downloaded over HTTPS with mandatory SHA-256 checksums, extracted with traversal/symlink/size limits, validated against signed manifests, and rolled back on verification failure.

• Real code structure: @babel/parser AST extraction for TypeScript/JavaScript, resolving relative, workspace, and tsconfig path aliases into symbol tables and file-level code-graph edges.

• Full-file integrity: Streamed SHA-256 over entire files plus bounded chunk hashes, removing any prefix blind spots.

• Shared memory foundation: Append-only hash-chained memory_events, namespaces, actor identities, optimistic concurrency with conflict proposals, and bi-temporal validity (asOf retrieval).

• Honest retrieval: Hybrid FTS5 + AST symbols + code graph + local feature-hash reranking with per-hit explanations and path/line evidence.

Monorepo Build & Test

For developers contributing to ProjectMind:

# 1. Install dependencies & link npm workspaces
npm install

# 2. Compile all packages, adapters, apps, and test suites
node scripts/build.js

# 3. Run the complete automated test suite (93/93 tests passing)
node scripts/test.js

# 4. Run the retrieval/freshness benchmark
node scripts/benchmark.js

# 5. Build verified release assets (core archive + 9 plugin bundles + SHA256SUMS)
node scripts/package-release.js

Documentation Guides

• Installation Guide (INSTALL.md) — Comprehensive cross-platform installation instructions, options, and offline setups.

• Troubleshooting Guide (TROUBLESHOOTING.md) — Diagnostic workflows, recovery commands, backup restoration, and solutions for common issues.

• Security Architecture (SECURITY.md) — Local-first guarantees, secret exclusion engine, path traversal defense, and prompt injection mitigation.

• Linux Guide (LINUX.md) — Linux distributions, XDG directory compliance, file descriptor tuning, and headless/systemd configurations.

• Windows Guide (WINDOWS.md) — PowerShell setup, execution policies, path handling (drive letters, spaces, Unicode, UNC), and Windows Terminal.

• Marketplace Specification (MARKETPLACE.md) — Distribution model, native agent marketplace integration, packaging, and catalog metadata.

• Plugin Development Guide (PLUGIN_DEVELOPMENT.md) — Authoring new plugins, Plugin SDK APIs, lifecycle events, and testing.

• Release Engineering (RELEASE.md) — Release checklists, automated packaging, checksum verification, and publishing workflows.

• Implementation Status (docs/IMPLEMENTATION_STATUS.md) — What is implemented and tested vs. experimental vs. planned, with known limits.

• Memory Model (docs/MEMORY_MODEL.md) — Namespaces, actors, append-only events, temporal validity, conflicts, and asOf retrieval.

• Repair & Verification Report (PROJECTMIND_REPAIR_REPORT.md) — Detailed audit report, fixes, and measurements.

License

ProjectMind is open-source software licensed under the MIT License.