Database Auditing (Doctor)

Keep your engrams database healthy and up-to-date. The doctor command automatically scans your knowledge base for broken links, missing files, stale decisions, and unlinked context.

Running the Doctor

Run the command from any workspace directory to perform a complete database audit:

engrams doctor

Audit Checks Performed

The doctor performs four key checks on your engrams database:

1. Missing File Anchors

Checks all registered file anchors (links from decisions or patterns to specific paths on disk) and verifies that the target files or directories still exist. If a file was renamed, moved, or deleted, it reports it as missing.

2. Dangling Links

Checks relationships (edges) in the workspace knowledge graph and verifies that both the source entity and the target entity still exist in the database. If an entity was deleted but the relation remains, it is flagged as dangling.

3. Stale Decisions

Detects when an active decision might need to be re-evaluated. If a decision has a registered commit_sha and file anchors, the doctor checks the git history of those anchored files. If any of those files have been modified since the decision's commit, the decision is flagged as stale.

4. Unlinked Decisions

Identifies active decisions that have a commit_sha associated with them but do not have a Pull Request (PR) link attached. This ensures all decisions made in the codebase are properly traced to their implementation PR.

Example Output

The command outputs a structured JSON report detailing the health of your database:

{
  "missing_anchor_paths": [
    {
      "item_type": "decision",
      "item_id": 12,
      "path": "src/old_auth.rs"
    }
  ],
  "dangling_links": [
    {
      "id": 4,
      "source": "system_pattern:2",
      "target": "decision:8"
    }
  ],
  "stale_decisions": [
    {
      "id": 5,
      "summary": "Use PostgreSQL for caching",
      "commit_sha": "a1b2c3d4",
      "changed_paths": [
        "src/db/cache.rs"
      ]
    }
  ],
  "unlinked_decisions": [
    {
      "id": 9,
      "summary": "Switch to rustls for TLS connection"
    }
  ],
  "git": "ok",
  "ok": false
}

AI Agent Integration

For AI agents, it is highly recommended to run engrams doctor periodically. Agents can use the output of the doctor command to proactively clean up obsolete anchors, link decisions to relevant PRs, or alert you when a modified codebase drifts from the documented architectural decisions.