Skip to main content
Glama
pollux-mcp

pollux-mcp

by Wsyjq

Pollux

A complete, local-first project memory for AI coding agents: self-owned engine, governance, diagnostics, and per-file dossiers in one package.

Status: early alpha. The repository is not published to PyPI yet. The name: Pollux is the immortal twin of Castor in Gemini. Here events.jsonl is Castor — the mortal, append-only record that eventually archives away — while the distilled summary.md is Pollux, the memory that stays alive; one cannot exist without the other. Relationship to projectmem: the on-disk format (.projectmem/ layout, six typed events, derived summary.md) is compatible with projectmem 0.2.x so existing memories carry over without migration, but this project no longer depends on or wraps that package — the engine is self-owned, fixing its architectural limits (unindexed precheck, full-rewrite-per-event, cwd-only capture, English-only classification, no archival, no locking).

简体中文

CI

Why this exists

Memory tools can create files and expose MCP commands, but a reliable engineering workflow needs more than storage:

  • A clear boundary between append-only history and directly maintained current state.

  • Conservative defaults instead of silently enabling hooks or global memory inheritance.

  • Repeatable Agent instructions across OpenCode, ZCode, Claude, Cursor, and Codex.

  • A doctor command that can prove the configured memory root, privacy profile, hook behavior, and accidental secret exposure.

  • A real project-family mode: memory anchored at a parent of several repos, with walk-up discovery, cross-process locking, and parent-anchored auto-capture.

  • Performance that holds as the memory grows: indexed precheck, incremental regeneration, and reversible archival.

Related MCP server: MemoSaver

Features

  • pollux init: idempotent memory bootstrap with conservative defaults.

  • pollux doctor: structured configuration, privacy, hook, and secret audit.

  • pollux render: client-specific MCP configuration for six AI clients.

  • Memory commands with upstream-compatible semantics: log, attempt, fix, decision, note, show, search, precheck, context, regenerate.

  • pollux archive: reversible lifecycle for closed, old issues and (opt-in) old decisions, dry-run first.

  • pollux backup: verified whole-memory snapshots — the irreplaceable event log lives outside git, so it needs its own safety net.

  • Budgeted MCP reads: get_summary returns a bounded digest when the full file would exceed the client's size budget (older entries used to be silently truncated away); search_events ranks by relevance.

  • pollux capture: bilingual (English + zh-CN) commit/merge classification, anchored by walk-up discovery, deduplicated by commit hash.

  • pollux hooks: managed, runtime-pinned, advisory git hooks.

  • pollux dossier: repository-agnostic per-file engineering dossiers (responsibility cards + memory + Git evidence).

  • pollux mcp: the fifteen-tool MCP server (same tool names as the historical surface, so existing agent workflows keep working).

  • Team, private, and project-family profiles; atomic marked-block updates that preserve existing AGENTS.md and CLAUDE.md content.

  • UTF-8 output for non-interactive Windows automation without overriding explicit user settings.

  • Runtime dependencies: only mcp>=1.2,<2; the CLI itself is standard library.

Installation

Until the first public release, install from a local checkout:

python -m pip install -e .

The package exposes the pollux (CLI) and pollux-mcp (server) commands.

Quick start

Team profile

The distilled map, plan, summary, issues, and instructions may be committed. Raw events and runtime files are ignored.

pollux init /path/to/repo --profile team --client opencode
pollux doctor /path/to/repo

Private profile

The complete .projectmem/ directory is ignored.

pollux init /path/to/repo --profile private --client claude

Project-family profile

Use only for tightly related repositories that intentionally share one project map and event history. The memory root must be an ancestor of the project.

pollux init /workspace/repo-a \
  --profile family \
  --memory-root /workspace \
  --client codex

Hooks in family mode are supported: pollux's own hooks resolve the memory by walking up from the Git root, so --enable-hooks works with a parent memory root.

Where the memory lives

pollux init writes only the memory root and the two rule files — nothing else in your repository. In the team and private profiles the memory root is <repo>/.projectmem/; in the family profile it is the .projectmem/ of the shared parent directory, discovered by walking up from each repository.

<repo>/                      # team/private: the repository; family: the shared parent
├── AGENTS.md                # governance rules, marked block          — committed
├── CLAUDE.md                # the same rules for Claude               — committed
└── .projectmem/             # the memory root
    ├── events.jsonl         # append-only raw history                — never committed
    ├── summary.md           # derived digest                          — committed in team
    ├── issues/              # derived per-issue history               — committed in team
    ├── PROJECT_MAP.md       # current structure, hand-maintained
    ├── plan.md              # current intent, hand-maintained
    ├── config.toml          # memory configuration
    ├── AI_INSTRUCTIONS.md   # agent workflow instructions
    ├── archive/             # reversible archive (pollux archive)
    └── cache/, write.lock   # runtime state                           — never committed

Every profile ignores the raw event log and runtime state; the private profile ignores the whole .projectmem/ directory; the team profile commits the distilled files (summary, issues, map, plan, configuration, instructions). Git hooks are only installed under <repo>/.git/hooks/ and only with --enable-hooks.

Conservative defaults

pollux init keeps automation opt-in: Git hooks require --enable-hooks (and pollux hooks install). Global-memory auto-promotion stays off; the global gotcha store is read-only by default.

This sequence is intentional: establish an accurate project map and verify active MCP writes before adding automation.

Commands

pollux init [PATH] [--profile team|private|family] [--enable-hooks]
pollux doctor [PATH] [--profile auto|team|private|family] [--json]
pollux render opencode|zcode|claude|cursor|codex|dsh [PATH]
pollux log|attempt|fix|decision|note <text> [--at loc] [--root DIR]
pollux show|regenerate [--root DIR]
pollux search <query> [--regex] [--failed-only] [--all]
pollux precheck [files...] [--level info|warn|block] [--json]
pollux context [--tokens N] [--focus AREA]
pollux archive --before DATE [--decisions-before DATE] [--dry-run] [--status] [--restore]
pollux backup [--to DIR] [--verify ZIP]
pollux capture commit|merge [--repo-root DIR]
pollux hooks install|uninstall [--repo DIR]
pollux dossier <path> [--validate] [--emit-schema]
pollux mcp

Use pollux <command> --help for all options.

What doctor checks

  • The nearest initialized memory root and expected memory files.

  • The effective team/private/family profile.

  • Agent workflow markers and source-of-truth rules.

  • Runtime and raw-event .gitignore policy.

  • Whether raw events.jsonl is tracked by Git.

  • Both project and shared-memory roots when using the family profile.

  • Legacy projectmem hook blocks (migration hint) and pollux hook runtime drift.

  • Windows hook paths and unresolved runtime pins.

  • OpenCode MCP root mismatch when opencode.json exists.

  • Common credential patterns without printing the matched value.

doctor --json provides machine-readable output suitable for CI.

Source-of-truth policy

Data

Owner

Direct editing

.projectmem/events.jsonl

pollux engine append operations

No

.projectmem/summary.md

pollux engine regeneration

No

.projectmem/issues/*.md

pollux engine regeneration

No

.projectmem/archive/

pollux archive (reversible)

No

.projectmem/PROJECT_MAP.md

Contributors and Agents

Yes

.projectmem/plan.md

Contributors and Agents

Yes

Non-goals for v0.2

  • Uploading memory to a hosted service.

  • Automatically modifying global AI-client configuration.

  • Treating heuristic Git backfill as verified design history.

  • Guaranteeing that a regex secret scan replaces dedicated secret-scanning tools.

Development

python -m unittest discover -s tests -v
python -m ruff check .
python -m build
python -m twine check --strict dist/*

See CONTRIBUTING.md, architecture, and the threat model.

License

Pollux is released under the MIT License. Dependency attribution is listed in THIRD_PARTY_NOTICES.md.

Available Tools

15 tools
add_decisionB

Record an architectural/product decision with its rationale.

Inputs: summary (required), location, supersedes. Returns: result

add_noteB

Record a gotcha, setup detail, or durable context.

Inputs: summary (required), location. Returns: result

get_contextA

Token-budgeted context block biased toward failures and decisions.

Read-only.

Inputs: focus, tokens, recent_days. Returns: result

get_global_gotchasA

Read cross-project gotchas from the shared global store.

Read-only. Auto-promotion into this store stays OFF by default in pollux (conservative governance); entries come from explicit curation.

Inputs: library. Returns: result

get_instructionsA

Load the project's mandatory AI workflow rules (AI_INSTRUCTIONS.md).

Read-only; call at session start.

Inputs: no named parameters. Returns: result

get_issueA

Read one issue's full history (token-efficient vs the whole summary).

Read-only.

Inputs: issue_id (required). Returns: result

get_planA

Read plan.md — the team's intent (ideas, active plans, next steps).

Returns 'No plan found.' if not initialized. Read-only.

Inputs: no named parameters. Returns: result

get_project_mapA

Read the structural layout (PROJECT_MAP.md).

Returns 'No project map found.' if not initialized. Read-only.

Inputs: no named parameters. Returns: result

get_scoreA

Failure-prevention score with the formula disclosed.

Read-only; computed from events.jsonl on each call.

Inputs: no named parameters. Returns: result

get_summaryA

Read the distilled project memory (summary.md).

Small memories return the full file; when the summary exceeds the MCP size budget (where client-side truncation would silently hide older entries), a bounded digest is returned instead with pointers to get_issue/search_events/pollux show.

Inputs: no named parameters. Returns: result

log_issueA

Open a new issue and mark it active. Call BEFORE writing fix code.

Inputs: summary (required), location. Returns: result

precheck_fileA

Check a file's memory before modifying it: open issues, failed and partial attempts, stale decisions, churn. Read-only.

Inputs: file_path (required). Returns: result

record_attemptA

Record a fix attempt IMMEDIATELY after it fails, partially works, or works. Each distinct approach is its own call — never batch them.

Inputs: summary (required), outcome, issue_id, location. Returns: result

record_fixA

Record the confirmed fix and close the issue. Only call with evidence (test passed, error gone, or user confirmed).

Inputs: summary (required), issue_id, location. Returns: result

search_eventsA

Search the event log, most relevant first (open issues, unresolved failures, recency, and file-path hits rank higher). Empty result returns a friendly message, not an error. Read-only.

Inputs: query (required), limit, include_archived. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 15 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, especially the write operations for issue lifecycle, attempts, fixes, decisions, and notes. However, get_summary, get_context, and search_events all surface overlapping project-memory information, and record_attempt's 'works' case creates some ambiguity with record_fix.

    Naming Consistency5/5

    Tool names consistently follow a verb_noun pattern in lowercase snake_case: get_* for reads, and log_/record_/add_ for writes. The pattern is easy to predict and there are no mixed naming conventions or vague generic verbs.

    Tool Count4/5

    At 15 tools, the server sits at the upper edge of a reasonable scope. Each tool corresponds to a meaningful memory or issue action, but the number of read-only context retrieval tools is slightly high and some could potentially be consolidated.

    Completeness4/5

    The core failure-prevention loop is well covered: precheck, log issue, record attempt, record fix, plus decision and note persistence. However, there is no write/update path for project map or plan files, and global gotchas are read-only, leaving minor lifecycle gaps.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      MCP server for persistent, cross-session, local-first memory for AI agents, storing memories as Markdown files with SQLite indexing for hybrid search.
      24
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Local-first MCP server that persists AI coding agent memory and session context, enabling seamless resume across sessions with searchable memories and checkpoints.
      7 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that provides offline-first, persistent memory for AI coding assistants. It captures project decisions and conventions into a local SQLite database and syncs them to tool-specific memory files like CLAUDE.md and AGENTS.md.
      4 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A local-first MCP server providing persistent, layered memory (episodic, semantic, procedural, resource) for AI agents, with search, versioning, and session management via a single SQLite file.
      78 npm
      3
      MIT