# CogZ (oci · ghcr.io/balaianu/cogz)

Local-first engineering cognition for AI coding agents — persistent memory over your codebase.

- Trust score: 45/100 (low)
- Change this week: +3
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-11-04

## Components

- oci · `ghcr.io/balaianu/cogz`: 45/100 (this document), [markdown](https://verifymcp.io/servers/balaianu-cogz/ghcr-io-balaianu-cogz.md), [page](https://verifymcp.io/servers/balaianu-cogz/ghcr-io-balaianu-cogz)

## Channel facts

- Registry: `oci`
- Package: `ghcr.io/balaianu/cogz`
- Version: `0.6.8`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-11-04.

- **Supply Chain Security**: 0/100
  - No malware scan is available for this kind of package: the supply-chain vendors we use do not cover it. This is a permanent gap in our coverage, not a finding about the package.
  - Known CVEs could not be checked: this artifact ships no SBOM or dependency manifest, so there is no dependency list to read.
  - Install-script risk not yet assessed.
  - Dependency health could not be checked: this artifact ships no SBOM or dependency manifest, so there is no dependency list to read.
- **Provenance & Transparency**: 35/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - License check failed: no license is declared.
  - Actively maintained (last published 3 days ago).
  - Publishes a security disclosure policy (SECURITY.md).
- **Schema Quality & AI Usability**: 63/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 2394 tokens (~159/item across 15 items; 15 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 70/100
  - Stability observed for 21 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 90/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 70% of tool parameters carry a description.
- **Tool Safety**: 100/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - We read all 15 captured tool definition(s), and no name or description among them implies an irreversible operation.
  - An AI judge read all 16 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a current MCP spec version (2026-07-28).

**Unverified: 1 category.** A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.

## Install

### How do I install the CogZ MCP server?

CogZ runs locally as a container image, launched with docker run --rm -i ghcr.io/balaianu/cogz:0.6.8. Ready-made configuration for Claude, Cursor, VS Code, Codex and 3 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add balaianu-cogz -- docker run --rm -i ghcr.io/balaianu/cogz:0.6.8
```

### Cursor

```json
{
  "mcpServers": {
    "balaianu-cogz": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "ghcr.io/balaianu/cogz:0.6.8"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "balaianu-cogz": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "ghcr.io/balaianu/cogz:0.6.8"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add balaianu-cogz -- docker run --rm -i ghcr.io/balaianu/cogz:0.6.8
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "balaianu-cogz": {
      "type": "local",
      "command": [
        "docker",
        "run",
        "--rm",
        "-i",
        "ghcr.io/balaianu/cogz:0.6.8"
      ],
      "enabled": true
    }
  }
}
```

### Hermes

```yaml
mcp_servers:
  balaianu-cogz:
    command: "docker"
    args: ["run", "--rm", "-i", "ghcr.io/balaianu/cogz:0.6.8"]
```

### Netclaw

```json
{
  "McpServers": {
    "balaianu-cogz": {
      "Transport": "stdio",
      "Command": "docker",
      "Arguments": [
        "run",
        "--rm",
        "-i",
        "ghcr.io/balaianu/cogz:0.6.8"
      ]
    }
  }
}
```

### Other

```json
{
  "mcpServers": {
    "balaianu-cogz": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "ghcr.io/balaianu/cogz:0.6.8"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-11-03 (score 45, +1)

No change was recorded against any check on this day. Stability & Change Management went from 63 to 67. That category is still filling its 30-day observation window: 19 days of observed history at the previous scan, 20 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-31 (score 44, +1)

- [functional] Package version: 0.6.6 → 0.6.8

### 2026-10-29 (score 43, +1)

No change was recorded against any check on this day. Stability & Change Management went from 47 to 50. That category is still filling its 30-day observation window: 14 days of observed history at the previous scan, 15 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-27 (score 42, +1)

- [functional] Package version: 0.6.5 → 0.6.6

### 2026-10-26 (score 41, 0)

- [functional] Package version: 0.6.3 → 0.6.5
- [functional] Package version: 0.6.3 → 0.6.4

### 2026-10-25 (score 41, +1)

No change was recorded against any check on this day. Stability & Change Management went from 33 to 37. That category is still filling its 30-day observation window: 10 days of observed history at the previous scan, 11 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-24 (score 40, 0)

- [functional] Package version: 0.5.8 → 0.6.3

### 2026-10-23 (score 40, +1)

No change was recorded against any check on this day. Stability & Change Management went from 27 to 30. That category is still filling its 30-day observation window: 8 days of observed history at the previous scan, 9 at this one. The score rises as the window fills, whether or not the server changes.

## MCP tools (15)

### `capture_event` (~172 tokens)

Capture a lifecycle event — called by hook scripts, not intended for direct use. session_start/prompt_submit return context packs; file_save reindexes and may return rules governing the edited file; session_end runs consolidation.

Input parameters:

- `event_type` (string, required): Event type: session_start, prompt_submit, pre_tool_use, post_tool_use, file_save, session_end.
- `file_path` (string|null): Saved file path, relative to repo root (for file_save).
- `prompt` (string|null): Prompt text (for prompt_submit).
- `repo` (string, required): Absolute path to the project root containing `.cogz/`.
- `tool_name` (string|null): Tool name (for pre_tool_use, post_tool_use).
- `tool_result` (string|null): Tool result summary (for post_tool_use).

### `consolidate` (~78 tokens)

Run deferred consolidation — promote supported observations to rules, merge confirmed duplicates. Housekeeping, not a write path; dedup and contradiction checks already run on every insert.

Input parameters:

- `dry_run` (boolean): If true, report what would be consolidated without making changes.
- `repo` (string, required): Absolute path to the project root containing `.cogz/`.

### `create_entity` (~390 tokens)

Create a knowledge-layer entity. `entity_type` picks the lifecycle, not the topic — ask what the entry IS: 'observation' = something that happened (bug found, surprising behavior, decision noticed) — raw, append-only, unvalidated; consolidation promotes the good ones to rules. 'rule' = a verified directive agents must always follow (conventions, constraints) — pushed into every context pack; change via supersede, not edits. 'knowledge' = a curated reference doc (architecture, gotchas, design decisions) — the only editable type (update_knowledge). Requires: content always; title+category for knowledge.

Input parameters:

- `category` (string|null): Category — required for `knowledge` (e.g. architecture, decisions, gotchas). Ignored otherwise.
- `confidence` (number|null): `rule` only: confidence 0..1.
- `content` (string, required): Entity body. Required for all types.
- `entity_type` (string, required): Which lifecycle class to create: `observation` (raw finding, append-only, unvalidated), `rule` (verified directive, always delivered in packs, supersede to change), or `knowledge` (curated reference…
- `references` (array|null): UUIDs of entities this entry references (code or knowledge).
- `repo` (string, required): Absolute path to the project root containing `.cogz/`.
- `source` (string|null): `observation` only: who or what produced it. Default: "agent".
- `supporting_ids` (array|null): `observation` only: UUIDs of observations this one supports — creates `supports` edges for promotion consolidation.
- `tags` (array|null): `knowledge` only.
- `title` (string|null): Title. Required for `knowledge`; auto-generated for observation/rule when omitted.

### `find_orphans` (~101 tokens)

Find code entities with no incoming calls/imports/extends edges — dead-code candidates. Use during cleanup audits. Entry points like main() surface by design; test code is excluded.

Input parameters:

- `entity_type` (string|null): Code entity type to check: function, class, file, or module. Default: functions and classes.
- `limit` (integer|null)
- `repo` (string, required): Absolute path to the project root containing `.cogz/`.

### `get_callers` (~101 tokens)

Find entities that call this function — answers 'who calls X?' with resolved call edges, not text matches. Use instead of grepping for the name when you need real callers (not comments, strings, or same-named functions).

Input parameters:

- `entity_id` (string, required): Entity ID whose callers to find (function, method).
- `limit` (integer|null)
- `repo` (string, required): Absolute path to the project root containing `.cogz/`.

### `get_context` (~162 tokens)

Assemble a context pack — a scoped, ranked bundle of orientation, rules, relevant code, and knowledge for a task query. Use at the start of substantial work on a topic instead of reading files broadly — narrower than a session-start pack, broader than a single search.

Input parameters:

- `include_stale` (boolean|null)
- `max_tokens` (integer|null)
- `mode` (string|null)
- `query` (string|null)
- `record` (boolean|null): Record this call as a delivery in usage telemetry. Defaults to true — pass false to inspect a pack without bumping access counts, opening a delivery, or closing pending usage as misses.
- `repo` (string, required): Absolute path to the project root containing `.cogz/`.

### `get_impact` (~118 tokens)

Transitive dependents of an entity — what breaks or needs updating when it changes (incoming calls/imports/extends up to max_depth hops), plus knowledge that references it. Use before renaming, deleting, or changing a signature.

Input parameters:

- `entity_id` (string, required): Entity ID to analyze.
- `limit` (integer|null)
- `max_depth` (integer|null): Max dependency hops to traverse (default 2, capped at 4).
- `repo` (string, required): Absolute path to the project root containing `.cogz/`.

### `get_status` (~63 tokens)

CogZ system status — entity counts, DB stats, model availability, staleness. Use to check the index is fresh and retrieval is at full capability before relying on it.

Input parameters:

- `repo` (string, required): Absolute path to the project root containing `.cogz/`.

### `list_entities` (~85 tokens)

List IDs and titles for all entities of a type. Use to enumerate a type or resolve an entity_id for get_callers/get_impact — returns no content; for substance use search or query_* tools.

Input parameters:

- `entity_type` (string, required)
- `repo` (string, required): Absolute path to the project root containing `.cogz/`.
- `status` (string|null)

### `query_entities` (~215 tokens)

Browse knowledge-layer entities of one type — 'observation' (raw findings, recency order), 'rule' (verified directives, confidence order), or 'knowledge' (curated docs). Use to enumerate what exists before writing (avoid duplicates) or to review a type — for ranked retrieval on a question use search; for code entities use list_entities or search.

Input parameters:

- `category` (string|null): `knowledge` only.
- `entity_type` (string, required): `observation` | `rule` | `knowledge`. For code entities use `list_entities` or `search` instead.
- `limit` (integer|null)
- `references` (string|null): `observation`/`rule` only: filter to entities referencing this target UUID.
- `repo` (string, required): Absolute path to the project root containing `.cogz/`.
- `status` (string|null): Status filter. Default: active only; `all` for every status.
- `tags` (array|null): `knowledge` only.

### `reject_entity` (~173 tokens)

Reject a knowledge-layer entity — writes `status: rejected` (and an optional `rejected_reason`) into its canonical file, then syncs so the status lattice validates the transition. Only `active` entities can be rejected; verify a stale one first if it must be ruled wrong. This is a verdict, not an edit — do not use it for content changes. Rejected entities stay on record: retrieval filters them out, and dedup can warn when a matching claim resurfaces.

Input parameters:

- `id` (string, required): UUID of the entity to reject.
- `reason` (string|null): Why the entity is rejected — stored as `rejected_reason` in the file's frontmatter so the verdict carries its evidence.
- `repo` (string, required): Absolute path to the project root containing `.cogz/`.

### `search` (~230 tokens)

Ranked search across all entities — code (functions, files, classes) plus rules, observations, and knowledge — using hybrid lexical + semantic retrieval with graph expansion. Use when you know the concept but not the exact name, or want related entities surfaced automatically. For exact identifier/text matches, grep is faster and equally precise.

Input parameters:

- `before` (integer|null): Only use git history committed before this unix timestamp for the co-change channel.
- `code_search` (boolean|null): Use the code model (CodeRankEmbed) for query embedding. Applies the CodeRankEmbed query prefix for code-focused search.
- `entity_type` (string|null)
- `expand` (boolean|null)
- `limit` (integer|null)
- `query` (string, required)
- `record` (boolean|null): Record this call as a delivery in usage telemetry. Defaults to true — pass false for inspection reads that must not bump access counts, open deliveries, or feed mining signals.
- `repo` (string, required): Absolute path to the project root containing `.cogz/`.
- `status` (string|null)

### `suggest_observations` (~115 tokens)

Mine recent session usage for observation candidates — zero-hit packs followed by edits, hot files, error→fix sequences. Use at natural stopping points to capture what the session learned; confirm salient suggestions via create_entity.

Input parameters:

- `days` (integer|null): How far back to mine events and usage, in days (default 7).
- `limit` (integer|null): Max candidates to return (default 10, capped at 50).
- `repo` (string, required): Absolute path to the project root containing `.cogz/`.

### `update_knowledge` (~108 tokens)

Update an existing knowledge entry's content — use to correct or extend documentation when facts change. The only entity type allowing in-place edits; observations and rules are append-only.

Input parameters:

- `category` (string|null)
- `content` (string, required)
- `id` (string, required)
- `references` (array|null)
- `repo` (string, required): Absolute path to the project root containing `.cogz/`.
- `tags` (array|null)
- `title` (string|null)

### `verify_knowledge` (~130 tokens)

Re-verify a knowledge entity against its referenced code — re-stamps verified_against provenance, clears drift annotations, and reactivates the entity if it was stale. Use after reading drift-flagged or stale knowledge and confirming it is still accurate — not for changing content (use update_knowledge instead).

Input parameters:

- `allow_dead_refs` (boolean): Reactivate even when some references are dead — asserts the claim holds despite missing anchors.
- `id` (string, required): UUID of the knowledge entity to verify.
- `repo` (string, required): Absolute path to the project root containing `.cogz/`.

## Diagnostics

Captured diagnostic sections: Provenance. The full working is on the page: https://verifymcp.io/servers/balaianu-cogz/ghcr-io-balaianu-cogz#diagnostics

## Score history

- 2026-11-04: 45
- 2026-11-03: 45
- 2026-11-02: 44
- 2026-11-01: 44
- 2026-10-31: 44
- 2026-10-30: 43
- 2026-10-29: 43
- 2026-10-28: 42
- 2026-10-27: 42
- 2026-10-26: 41
- 2026-10-25: 41
- 2026-10-24: 40
- 2026-10-23: 40
- 2026-10-22: 39
- 2026-10-21: 39
- 2026-10-20: 38
- 2026-10-19: 38
- 2026-10-18: 37
- 2026-10-17: 37
- 2026-10-16: 37
- 2026-10-15: 36
- 2026-10-14: 36
- 2026-10-13: 7
- 2026-10-12: 7
- 2026-10-10: 7
- 2026-10-09: 7
- 2026-10-06: 7

## Common questions

### What is the CogZ MCP server?

CogZ is an MCP server listed in the public MCP registry as io.github.balaianu/cogz. Local-first engineering cognition for AI coding agents, persistent memory over your codebase. This page covers its container image (ghcr.io/balaianu/cogz).

### Is the CogZ MCP server safe to use?

CogZ scores 45 out of 100 on VerifyMCP. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the CogZ MCP server expose?

CogZ exposes 15 tools: capture_event, consolidate, create_entity, find_orphans, get_callers, and 10 more. Their descriptions and schemas cost roughly 2,241 tokens of context every time the server is loaded.

### Is the CogZ MCP server still maintained?

CogZ is still listed as active in the MCP registry. We last reached this channel on 4 November 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

## Links

- GitHub Container Registry: https://ghcr.io/balaianu/cogz
- Repository: https://github.com/balaianu/CogZ
- Changelog RSS feed: https://verifymcp.io/servers/balaianu-cogz/ghcr-io-balaianu-cogz.xml
- Changelog JSON feed: https://verifymcp.io/servers/balaianu-cogz/ghcr-io-balaianu-cogz.json
- HTML version of this page: https://verifymcp.io/servers/balaianu-cogz/ghcr-io-balaianu-cogz