Pathmark

Stop re-explaining your repo each time you switch agents.

<p align="center"> <a href="https://www.npmjs.com/package/pathmark"><img src="https://img.shields.io/npm/dt/pathmark?label=npm%20downloads" alt="npm downloads"></a> <a href="https://www.npmjs.com/package/pathmark"><img src="https://img.shields.io/npm/dw/pathmark?label=weekly%20downloads" alt="weekly npm downloads"></a> <a href="https://scorecard.dev/viewer/?uri=github.com/hacksurvivor/pathmark"><img src="https://api.scorecard.dev/projects/github.com/hacksurvivor/pathmark/badge" alt="OpenSSF Scorecard"></a> </p> <p align="center"> <img src="https://raw.githubusercontent.com/hacksurvivor/pathmark/main/assets/pathmark-hero.png" alt="Pathmark local memory layer shared by Codex, Claude Code, opencode, and Gemini CLI" width="100%"> </p>

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

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 memory:

• One local JSONL store across harnesses.
• Standard MCP tools: remember, search_memory, recall_memory, session_trace, get_context, and 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 context with remember or create_conclusion; the next tool recovers it with recall_memory, search_memory, get_context, or ask_memory.

Pathmark sits below the agents as a memory bus for your coding workflow.

Tools

Pathmark exposes these MCP tools:

| Tool | Purpose | | --- | --- | | remember | Save a raw memory item. | | create_conclusion | Save a higher-signal durable conclusion or preference. | | search_memory | Search memories and conclusions. | | recall_memory | Transparent recall: returns context plus the exact memory IDs, timestamps, sources, matches, tags, and previews used. Accepts optional tags, exact ids, and compact includeRecords: false output. | | session_trace | Return a bounded chronological audit trail for one session: prompts, exact injected memory IDs, redacted tool inputs/results, and answers. | | get_context | Return compact context for a task or question. | | list_conclusions | List saved conclusions. | | delete_memory | Soft-delete a memory or conclusion by id. | | update_memory | Correct a record while preserving prior versions. | | supersede_memory | Replace an outdated record with a linked current record. | | purge_memory | Preview or apply permanent deletion by id, namespace, tags, source, or date. | | doctor_memory | Report duplicates, deleted/expired records, conclusions, and index health. | | compact_memory | Preview or apply deduplication, retention, and physical cleanup with an automatic backup. | | backup_memory | Create a point-in-time canonical JSONL backup. | | export_memory | Export a scoped mergeable JSONL bundle, optionally encrypted. | | ask_memory | Return relevant context, or synthesize with PATHMARK_CHAT_COMMAND if configured. | | chat | Chat-compatible alias for ask_memory; returns the retrieved context so the client can show what was used. | | get_config | Show local store configuration. |

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 auto-capture also recalls relevant memory automatically at session start and before non-trivial prompts, but recall_memory is the portable visible trace across harnesses.

Claude Code

claude mcp add pathmark -- pathmark

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 first when migrating another machine:

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

Codex Auto-Capture

Install Pathmark as the Codex memory adapter:

pathmark codex install --replace-legacy-hooks

This registers the Pathmark MCP server, enables Codex hooks, and removes old compatible hook commands from Codex. It does not delete or move memory files.

The Codex adapter is proactive by default:

• user prompts, final assistant answers, and tool activity are captured locally; intermediate Codex commentary is excluded;
• tool activity records include bounded redacted input previews and hashes, status, exit code, duration, and changed files when the hook provides them;
• tool-output hashes are captured for correlation, while output text remains private by default and requires PATHMARK_CODEX_CAPTURE_TOOL_OUTPUTS=on;
• activity records expire after 30 days and are physically capped at 5,000 records by default;
• session start/resume injects relevant workspace memory;
• each non-trivial user prompt searches the local store and injects matching memory as Codex additionalContext;
• when matching memory is found, Codex receives an instruction to call recall_memory with the exact pre-capture result IDs and workspace tag, so the UI cannot mistake the newly saved prompt for previously used memory;
• prompt context applies relevance and near-duplicate filtering before injection, and automatic visible recall omits the redundant full records copy;
• legacy transport envelopes and assistant progress updates are excluded from session-start and proactive relevance results, while remaining available to explicit raw search;
• no matching memory means no extra context is injected.

Set PATHMARK_CODEX_PROACTIVE_RECALL=off if you want Codex hooks to capture memory but stop prompt-time recall. Set PATHMARK_CODEX_VISIBLE_RECALL=off if you want prompt-time recall without the visible recall_memory tool-call request.

recall_memory is a point-in-time record of memory used before an answer. It intentionally does not include commands that run later. Use session_trace with the exact session ID to inspect the chronological prompt → injected memories → tools/results → final-answer trail. When explicitly enabled, output previews are capped at 2,000 characters and redacted before storage; hashes preserve correlation without storing output text by default. Upgrading an existing cursor migrates to final-answer-only parsing without duplicating previously captured user or final-answer turns. When the original transcript is available, exact legacy phase: "commentary" records are soft-deleted by timestamp and text during that migration.

Use --replace-legacy-hooks when you want Pathmark hooks to take over from earlier compatible hook commands. Without it, Pathmark installs alongside existing hook commands.

Check the adapter status:

pathmark codex status

The status output is JSON and includes Pathmark hook state, MCP registration state, legacy hook presence, the active store paths, and the current record count.

Remove Pathmark hooks and MCP registration without deleting memory:

pathmark codex uninstall

Configuration

| Variable | Default | Description | | --- | --- | --- | | PATHMARK_STORE_DIR | ~/.pathmark/memory | Directory for memory.jsonl. | | PATHMARK_MAX_SEARCH_RESULTS | 12 | Default search limit. | | PATHMARK_CODEX_PROACTIVE_RECALL | on | Automatically inject relevant Pathmark context before non-trivial Codex prompts. Use off to capture without prompt-time recall. | | `PA