Pathmark

Pathmark

Carry intent across agents without turning stale code facts into hidden memory.

What's New — v0.1.17

Pathmark v0.1.17 stops Claude Code from gating every memory lookup:

• pathmark setup claude-code --apply-permissions adds allow rules for Pathmark's ten local read-only tools, so recall and search run without a permission prompt, and in auto mode without a safety-classifier round-trip that can fail transiently;
• it backs up ~/.claude/settings.json, adds only missing rules, keeps every other setting, and never rewrites a file it cannot parse;
• the allow list is tested against the tools' own readOnlyHint/openWorldHint annotations, so anything that writes, deletes, or may call an external model always keeps its prompt.

See the v0.1.17 release notes or the complete changelog. The npm badge above always shows the currently published version.

Pathmark gives Codex, Claude Code, opencode, Gemini CLI, Cursor, and any MCP-capable harness one local intent and provenance layer. Save decisions, constraints, preferences, and approved conclusions once. Use them from the next agent without pasting a recap.

Code remembers implementation. Pathmark remembers intent. Repository code, architecture, tests, CI, and intentional agent instructions remain authoritative for how the software works. Raw sessions are searchable evidence, not automatically trusted truth.

Your context stays on disk at ~/.pathmark/memory/memory.jsonl. You do not need an account, hosted database, API key, or vendor backend to start.

OpenAI Build Week 2026

Pathmark is a Developer Tools submission for OpenAI Build Week 2026. The project existed before the challenge, so the submission is deliberately scoped to the meaningful extension built after the submission period opened on July 13, 2026.

During the eligible period, Codex with GPT-5.6 helped audit and extend Pathmark from a working local memory layer into safer long-running developer infrastructure:

• fixed a reproduced multi-process SQLite index race;
• added revision history, superseding, expiration, retention, diagnostics, backup, compaction, and preview-first hard purge;
• added namespace-scoped reads and writes plus default secret redaction;
• added scoped import/export, optional AES-256-GCM portable exports, local hybrid reranking, and portable harness ingestion;
• hardened CI and npm delivery with required CodeQL and dependency review, immutable Action pins, protected tags, OpenSSF analysis, and SLSA provenance.

The primary Codex session for this work is 019f5fc3-d7e6-7b41-8a30-d161c90b98fb. The qualifying release range is v0.1.6 through v0.1.7; the pre-challenge baseline is commit 4c0e87dfdbd2ba4c643abd8b887cc228bdb08b73.

See the Build Week implementation record for the before/after boundary, commit evidence, Codex collaboration details, and a fast judge test.

Why Pathmark

You do not work in one tool. You ask Codex to patch, Claude Code to review, opencode to clean up, and Gemini CLI to challenge the plan. Each tool starts cold unless you carry the context across.

Pathmark gives those tools one place to read and write intent and evidence:

• One local JSONL store across harnesses.
• Standard MCP tools include remember, search_memory, recall_memory, session_trace, rate_recall, consolidate_memory, audit_memory, and conclusion-first chat / ask_memory.
• Client-side synthesis by default, so your coding agent reads the context and answers.
• Optional Codex CLI, local command, and OpenAI-compatible synthesis modes.
• Plain files you can inspect, back up, delete, or migrate.

Pathmark stays provider-neutral. Codex gets one optional synthesis preset. The core server works with any MCP client that can use local tools.

Pathmark requires Node.js 22.5 or newer.

Cross-Harness Memory

You switch tools during a coding session:

• Codex fixes the failing test.
• Claude Code reviews the patch.
• opencode cleans the diff.
• Gemini CLI challenges the approach.

Pathmark keeps the notes in one store.

Point each harness at the same store:

Codex       \

Claude Code \ opencode > Pathmark MCP > ~/.pathmark/memory/memory.jsonl Gemini CLI / Cursor /

Install Pathmark in each harness and point them at the same PATHMARK_STORE_DIR. One tool saves raw context with remember or proposes a durable conclusion with create_conclusion; an approved conclusion and raw evidence can then be recovered with recall_memory, search_memory, get_context, or ask_memory.

Pathmark sits below the agents as an intent, evidence, and provenance bus for your coding workflow.

Tools

Pathmark exposes these MCP tools:

Quick Start

npm install -g pathmark

Then add the MCP server to your client.

Prefer npm for normal installs. To test the current GitHub main branch directly:

npm install -g --install-links=true github:hacksurvivor/pathmark

Generate a setup snippet for your harness:

pathmark setup list

pathmark setup claude-code pathmark setup opencode --json pathmark setup gemini-cli pathmark setup kimi

See docs/compatibility.md for Codex, Claude Code, opencode, Gemini CLI, OpenClaw, Hermes Agent, Grok CLI, Kimi, GLM, and generic MCP setups.

Codex

codex mcp add pathmark -- pathmark

Codex users can also enable auto-capture:

pathmark codex install --replace-legacy-hooks

When you want the visible "what memory did you use?" entry in Codex, Claude Code, Cursor, opencode, Gemini CLI, Grok-compatible MCP hosts, or any other MCP harness, call the recall_memory tool before answering. Codex session start injects an approved conclusion snapshot. Before non-trivial prompts, Codex recalls approved conclusions first and uses fresh scoped raw evidence only as a bounded fallback. recall_memory remains the portable visible trace across harnesses.

Claude Code

claude mcp add --scope user pathmark -- pathmark

pathmark setup claude-code --apply-permissions

The second command lets Pathmark's local read-only tools (recall, search, diagnostics) run without a permission prompt, including in auto mode, where they would otherwise wait on the safety classifier. It backs up ~/.claude/settings.json, adds only the missing allow rules, and leaves everything else untouched. Tools that write or delete memory still ask.

--scope user makes Pathmark available in every project; Claude Code's default scope only covers the current directory. For automatic capture and session-start recall (including after context compaction), merge the hooks block from pathmark setup claude-code into ~/.claude/settings.json.

Claude Code's built-in auto-memory lives in per-project folders the other agents cannot see. Bring it into the shared store as evidence (re-runnable; edits update in place with history, and records you delete in Pathmark stay deleted):

pathmark import-native claude-code --dry-run

pathmark import-native claude-code

opencode / Gemini CLI

Use the generated snippets:

pathmark setup opencode

pathmark setup gemini-cli

Claude Desktop

Add this to your Claude Desktop MCP config:

{

"mcpServers": { "pathmark": { "command": "pathmark", "env": { "PATHMARK_STORE_DIR": "~/.pathmark/memory" } } } }

Cursor

Add the same command to Cursor's MCP server settings:

{

"mcpServers": { "pathmark": { "command": "pathmark" } } }

Local Development

npm install

npm test npm run coverage

Run directly:

PATHMARK_STORE_DIR=.pathmark npm run dev

Import Legacy Memory

Pathmark can import a compatible local JSONL memory store without deleting or moving the source files.

npm run import:legacy -- --source-dir ~/old-codex-memory

Defaults:

Legacy source:   ~/.pathmark/legacy/codex

Pathmark target: ~/.pathmark/memory/memory.jsonl

The importer creates a memory.jsonl.backup-* file before writing, uses deterministic ids so reruns skip duplicates, and redacts obvious KEY=..., TOKEN=..., PASSWORD=..., and Bearer ... values. It uses the same store lock as live MCP and Codex writers, so an import cannot overwrite records captured concurrently.

Use a dry run fir