docqmind

docqmind is a local-first shared memory layer for AI-assisted software development. The public command is dqm.

Install

Install the dqm CLI globally (recommended):

npm i -g @docqminds/docqmind
dqm --version

Requires Node.js 22.14.0 or newer. npm installs the launcher and the native binary for your platform. This release supports macOS on Apple Silicon and Intel, glibc Linux on ARM64 and x64, and Windows x64. Linux musl, Windows ARM64, and other platforms are not supported yet.

One-off without a permanent install:

npx -y --package @docqminds/docqmind dqm --version

The examples below use dqm directly after a global install.

Search is keyword-based without semantic embeddings or vector retrieval; team synchronization and a local UI are not included. summary and context are available as memory-first rulebook helpers. CLI, MCP, and stored-data compatibility are treated as public interfaces and change deliberately.

Initialize a repository

From anywhere inside a Git repository:

dqm init

For scripts and agent integrations, select the project explicitly, accept safe defaults, and request JSON output:

dqm --root /path/to/project --json init --yes

Initialization creates local storage and, by default, wires supported AI clients so you do not need a separate setup step:

.docqmind/
├── config.toml
└── docqmind.db
.docqmindignore
AGENTS.md or AGENTS.override.md
.codex/config.toml
CLAUDE.md
.mcp.json
.cursor/rules/docqmind.mdc
.cursor/mcp.json
.grok/rules/docqmind.md
.grok/config.toml

The command is idempotent. It preserves valid existing configuration and database state, applies pending migrations, avoids duplicating .docqmind/ in .gitignore, and re-applies agent integration only when managed files are missing or safe to create. Conflicting existing client entries are left unchanged and reported; use dqm setup-agent all --write --force to replace only valid docqmind-managed content.

docqmind.db is a binary SQLite database, not a .sql source file. After successful human-readable initialization, dqm prints the next verification command (dqm doctor --client all).

To initialize storage only:

dqm init --yes --no-setup-agent

Configure project agents

dqm init already configures Codex, Claude Code, Cursor, and Grok by default. Use setup-agent to preview, re-apply, force-update, or target one client:

dqm setup-agent all
dqm setup-agent all --write
dqm setup-agent grok --write

Setup uses portable dqm --root . mcp entries and creates or structurally merges the clients' documented project files:

AGENTS.md or AGENTS.override.md
.codex/config.toml
CLAUDE.md
.mcp.json
.cursor/rules/docqmind.mdc
.cursor/mcp.json
.grok/rules/docqmind.md
.grok/config.toml

Grok project MCP lives in .grok/config.toml under [mcp_servers.docqmind], with workflow instructions in .grok/rules/docqmind.md. Shared Markdown files contain only a marked <!-- docqmind:start --> / <!-- docqmind:end --> block. Unrelated TOML, JSON, and Markdown content is preserved. Exact reruns are no-ops. A differing managed entry is reported as a conflict; use --write --force to replace only valid docqmind-managed content. Malformed or duplicated Markdown markers always require manual repair.

Use one client name instead of all to configure only that client. generic prints reusable MCP JSON and workflow Markdown but never writes files:

dqm setup-agent codex --write
dqm setup-agent grok --write
dqm setup-agent generic

The generated workflow asks agents to search durable project memory before substantive work, respect memory trust states, avoid secrets and transient reasoning, record substantive outcomes, and create handoffs for unfinished transfers.

Restart the configured client, trust the repository when required, and approve the project MCP server on first use. Then verify storage, managed files, the PATH-resolved dqm, MCP identity and instructions, required tools, and clean shutdown:

dqm doctor --client all
dqm doctor --client grok

Plain dqm doctor checks storage plus auto-detected integrations. Integration problems and pending supported migrations are warnings in this mode and exit successfully. An explicit --client makes that integration and its live MCP handshake required. Doctor is read-only and never applies migrations; run dqm init --yes when it reports pending migrations.

Index repository files (Beta)

Repository file indexing and file-chunk search are an opt-in Beta. Structured project memories remain available regardless of this setting. Enable the Beta for a repository, then build its local incremental index:

dqm feature enable file-indexing
dqm index

Check or change the setting at any time:

dqm feature status file-indexing
dqm feature disable file-indexing

Enabling does not scan automatically; run dqm index when ready. Disabling takes effect immediately and removes stored files, chunks, code symbols, containment edges, and their search projections while preserving every structured memory. New repositories and configurations without a [features] section default to disabled. The schema migration that introduces this setting also removes legacy file indexes, so existing users must explicitly enable the Beta and re-run dqm index.

Indexing respects .gitignore and .docqmindignore, applies non-overridable exclusions for secrets and internal state, skips binaries, oversized files, build outputs, dependencies, and symlinks, and stores repository-relative line ranges for every chunk. Files and chunks use BLAKE3 content hashes, so unchanged content is not rewritten and changed files are replaced atomically. Rust, Python, TypeScript, and TSX files also produce a rebuildable graph-lite symbol-and-containment projection from the same tree-sitter parse. JavaScript remains chunk-only. Structured memories remain authoritative, and dqm search remains memory/file-chunk only.

Read-only symbol exploration is a separate opt-in Beta access surface. After file indexing is enabled and an index exists, enable it explicitly:

dqm feature enable code-index
dqm explore "Session::refresh"
dqm --json explore "Session" --kind struct --path src --child-limit 20

dqm explore returns symbol kinds, names, qualified names, signatures, repository-relative inclusive line ranges, and immediate parent/child containment. It never returns source bodies. code-index is off by default and requires file-indexing; disabling it retains graph-lite data, which continues to update on later dqm index runs. Disabling file-indexing atomically disables both features and then removes the file and graph indexes. Calls, imports, inheritance, callers, recursive traversal, and impact-radius analysis are not part of this milestone.

Rust, JavaScript, TypeScript, TSX, and Python use syntax-aware declaration boundaries. Other UTF-8 text uses deterministic paragraph and line chunking. Useful controls include:

dqm index --path src --dry-run
dqm index --path src/auth --force
dqm --json index

JSON output reports new, changed, unchanged, removed, skipped, and failed counts without exposing rejected file contents or detected secrets. Indexing is keyword-based in this milestone; embeddings and vector retrieval are not required.

Record structured memory

After initialization, record a durable typed memory with dqm remember:

dqm remember \
  --kind decision \
  --status active \
  --title "Authentication method" \
  --body "Use email OTP. Password authentication is outside the MVP." \
  --created-by codex \
  --tag authentication

The status defaults to proposed when omitted. Human output is concise and never echoes the body:

Created decision memory <UUIDv7> (active): Authentication method

Use the global --json option to return the complete stored memory, including its body, object-shaped metadata, provenance, public UUIDv7, and RFC3339 UTC timestamps. Repeatable --tag values are trimmed, deduplicated, and merged into the tags array inside metadata.

An active memory can replace an existing memory atomically:

dqm remember \
  --kind decision \
  --status active \
  --title "Replacement decision" \
  --body "The new active guidance." \
  --supersedes <EXISTING_UUID_V7>

The replacement is inserted, the prior memory becomes superseded, and both records are linked in one transaction. Replacements must use --status active.

remember requires both .docqmind/config.toml and .docqmind/docqmind.db; it never initializes storage implicitly. Invalid memory input exits with code 2, uninitialized projects with 3, configuration or managed-file errors with 4, and database failures with 5.

Keep project memory healthy (rulebook, not diary)

docqmind works best as a small set of current rules the next agent can trust, not as a long diary of finished tasks.

1. Close stale work. Mark finished plans and tasks completed or outdated so they do not look open:

dqm list --kind task
dqm set-status --id <UUID_V7> --status completed

2. Keep few main memories. Prefer active decisions, constraints, conventions, must-not-break rules, and open questions. Skip one-off UI fixes unless they teach a lasting lesson.

dqm list --kind decision --kind constraint --kind convention --status active

3. Write rules, not stories. Bad: a long “we changed 12 files today…” permanent entry. Good: a short rule, where it lives in the repo, and what not to do.
4. Stamp real decisions yourself. Use --approved-by "Your Name" when creating a rule, or approve later:

dqm approve --id <UUID_V7> --by "Your Name" --activate

Agents must never invent human approval. 5. Save failures and open questions. Record useful failures and undecided questions so agents do not repeat mistakes. 6. After each real task, do two things: log the work with dqm_record_result, and if you learned a lasting rule, save that rule separately with dqm remember (or supersede an older one). 7. Replace old rules. When guidance changes, use --supersedes <uuid> instead of stacking two conflicting active answers. 8. Smarter file search is optional. Enable file indexing only when ready. Fix content first; better search on messy memory still returns messy answers.

Default search already hides rejected, outdated, and superseded memories. Ranking prefers active rulebook kinds (decision, constraint, convention, requirement) over completed work logs (result, handoff).

Read the project rulebook

dqm summary
dqm context "Implement authentication" --token-budget 4000

summary is an answer-first overview of active decisions, constraints, conventions, requirements, open questions/tasks, and useful failures. context packs a budgeted task packet with the same rulebook-first order so the next agent gets trusted guidance instead of a work diary.

Create a durable agent handoff

Use dqm handoff to transfer a task with explicit, structured context:

dqm handoff \
  --from claude \
  --to codex \
  --task "Implement organization invitations" \
  --summary "Persistence is complete; the HTTP route remains." \
  --requirement "Invitations expire after 24 hours" \
  --file src/invitations.rs \
  --completed-work "Added the persistence model" \
  --remaining-work "Add POST /api/invitations"

Every handoff requires a source, destination, task, summary, and at least one --remaining-work item. Repeatable options also capture decisions, previous attempts, acceptance criteria, risks, open questions, must-not-change boundaries, and completed work. File values must be repository-relative, but they do not need to exist yet.

The handoff is stored as a completed handoff memory. Its source agent is recorded as created_by; all sections are preserved in dqm.handoff.v1 metadata and rendered into a searchable body. Human output contains only the public ID and routing summary. Use global --json for the complete stored record or --quiet to suppress success output.

Search project knowledge and files

Search accepts natural questions, technical identifiers, routes, error constants, and path-like terms:

dqm search "Why did we avoid passwords?"
dqm search "ERR_TOKEN_EXPIRED"
dqm search "POST /api/invitations" --kind requirement
dqm search "Where is authentication implemented?"

Search always covers structured memories. When the file-indexing Beta is enabled, it also uses several safe FTS5 retrieval strategies across indexed file chunks, fuses their ranks, and then applies status, provenance, approval, memory kind, identifier, path, and exact-field signals. Active and human-approved rulebook memories (decisions, constraints, conventions, requirements) are preferred over completed work logs. Rejected, outdated, and superseded guidance is hidden by default; use --include-history when investigating earlier decisions. Old terminology can still find the active replacement of a superseded memory without presenting the old guidance as current.

Implementation-location questions such as Where is authentication implemented? are treated specially: location words are removed from retrieval, common authentication identifiers such as auth and authenticated are aligned, and matching source filenames and declarations receive an explainable boost. Production source is preferred over tests, broad documentation, generated artifacts, and lockfiles for this intent; those files remain searchable for direct queries.

Agents should use JSON mode. Every search response includes file_search_enabled. Memory results retain their complete existing shape; when the Beta is enabled, file results use result_type: "file_chunk" and include the complete chunk, repository-relative path, inclusive line range, language, BLAKE3 content hash, score, and match reasons:

dqm --json search "authentication method" --limit 5 --explain

Treat active and approved results as authoritative project guidance, proposed results as suggestions, and needs_verification results as evidence that must be checked. Use repeatable --kind, --status, and --path filters to narrow retrieval. Kind or status filters intentionally return memories only; path filters apply to both memories and files. --path docs matches both docs and its descendants. Search never accepts raw advanced FTS syntax; punctuation and operators are treated as query text.

Adjacent or verifiably overlapping matches from the same file are consolidated into bounded contiguous results. Consolidated results keep accurate inclusive line ranges and hash the returned combined content, reducing repeated and scattered hits from one implementation file.

Use project memory from an AI agent with MCP

dqm includes a local stdio MCP server for AI agents. The recommended project configuration is dqm setup-agent; the reusable project-relative stdio entry is:

{"command":"dqm","args":["--root",".","mcp"]}

The server exposes eleven tools: dqm_search, dqm_remember, dqm_record_result, dqm_handoff, dqm_get_memory, dqm_list, dqm_set_status, dqm_approve, dqm_summary, dqm_context, and dqm_explore. It does not open a port or contact a network service. The MCP client starts it as a child process and communicates through stdin/stdout. dqm_search searches memories by default and includes file chunks only when the file-indexing Beta is enabled. dqm_list browses open guidance without inventing a query. dqm_set_status closes finished tasks; dqm_approve stamps human approval (never invent it). dqm_summary and dqm_context return rulebook-first packets. dqm_explore is always discoverable but returns a nonfatal feature_disabled tool error until both file-indexing and code-index are enabled. Search, list, summary, context, and explore re-read project configuration for every call, so feature changes take effect without restarting the MCP server.

During MCP initialization the server also exposes the versioned docqmind-agent-workflow/v3 instructions. These server-wide instructions require memory search before substantive work, prefer a small active rulebook over work diaries, allow code exploration after memory search when already enabled, and prohibit agents from enabling features or indexing autonomously. Existing managed v1/v2 blocks are reported as outdated; replace them explicitly with dqm setup-agent <client> --write --force.

After completing or attempting work, agents should call dqm_record_result with a required task, outcome, and summary. Outcomes are completed, partial, or failed. Optional structured sections capture changed files, individual tests, failures, new decisions, discovered problems, open questions, and remaining work. Each test uses a name, a passed, failed, or not_run status, and optional details. The tool returns { memory, suggested_follow_ups }: the finalized result memory has kind=result and status=completed, while suggested_follow_ups lists lasting decisions, failures, and questions that should be saved separately with dqm_remember (they are not auto-created).

Agents can call dqm_handoff with the same sections accepted by the CLI. It requires from, to, task, summary, and a nonempty remaining_work array. Both tools store versioned metadata and a searchable body through the same atomic local memory path as dqm_remember; they do not infer test success or auto-enrich caller-supplied context.

Codex CLI and Codex app

Add the server from a terminal:

codex mcp add docqmind -- dqm --root /absolute/project/path mcp

Or add it to ~/.codex/config.toml (or a trusted project's .codex/config.toml):

[mcp_servers.docqmind]
command = "dqm"
args = ["--root", "/absolute/project/path", "mcp"]

Claude Code

Add a project-scoped stdio server:

claude mcp add --scope project docqmind -- dqm --root /absolute/project/path mcp

Run claude mcp get docqmind to verify the saved configuration.

Claude Desktop

Open Settings > Developer > Edit Config and add this entry to claude_desktop_config.json, then fully restart Claude Desktop:

{
  "mcpServers": {
    "docqmind": {
      "command": "dqm",
      "args": ["--root", "/absolute/project/path", "mcp"]
    }
  }
}

If the desktop application cannot find dqm, use the executable's absolute path as command.

Cursor

Create .cursor/mcp.json in the project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "docqmind": {
      "command": "dqm",
      "args": ["--root", "/absolute/project/path", "mcp"]
    }
  }
}

Other MCP clients

Configure a local stdio server named docqmind with executable dqm and arguments --root, the absolute project path, and mcp. No environment variables, URL, or authentication settings are required.

After connecting, use this smoke prompt:

Search project memory for the current authentication decision.

Active and human-approved memories are trusted project guidance. Proposed memories are suggestions, and needs_verification memories must be checked before relying on them. Rejected, outdated, and superseded memories are history and must not silently guide implementation. Search responses include complete memory provenance and trust state, plus indexed file chunks with paths and line ranges only when the file-indexing Beta is enabled.

MCP reserves stdout for newline-delimited JSON-RPC. Startup and safe operational diagnostics go to stderr; --verbose adds safe stderr detail without logging tool arguments, memory bodies, metadata, credentials, or protocol messages. The global --json and --quiet flags do not change MCP output. If a client cannot start the server, check its MCP stderr logs and verify the absolute project path, initialization state, configuration, database readability, and the executable path.

License

docqmind is available under the MIT License or the Apache License 2.0, at your option.