pathmark

Pathmark

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

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.

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, 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 for scoped visible recall.
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:

• prompt, tool, and transcript context are captured locally;
• 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 same query and workspace tag so the UI can show the exact usedMemories;
• 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.

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.
PATHMARK_CODEX_VISIBLE_RECALL	on	Ask Codex to call recall_memory when prompt-time recall found context, so the UI shows the exact usedMemories.
PATHMARK_SYNTHESIS_PROVIDER	client	client, command, codex, or openai-compatible.
PATHMARK_CHAT_COMMAND	unset	Command provider: receives a synthesized prompt on stdin and writes an answer on stdout.
PATHMARK_CODEX_COMMAND	codex	Codex provider command.
PATHMARK_CODEX_MODEL	unset	Optional Codex model override.
PATHMARK_OPENAI_BASE_URL	https://api.openai.com/v1	OpenAI-compatible API base URL.
PATHMARK_OPENAI_API_KEY	unset	OpenAI-compatible API key.
PATHMARK_OPENAI_MODEL	unset	Model id for OpenAI-compatible synthesis.
PATHMARK_CHAT_TIMEOUT_MS	120000	Synthesis command timeout.
PATHMARK_NAMESPACE	unset	Default namespace applied consistently to MCP reads and writes.
PATHMARK_REDACT_MCP_WRITES	on	Redact common secret-shaped values on remember, conclusion, update, supersede, import, and ingest paths.
PATHMARK_RETENTION_DAYS	0	Retention policy used by compaction; 0 disables age-based removal. Conclusions are retained.
PATHMARK_RERANK_COMMAND	unset	Optional local hybrid reranker. Receives query/candidates as JSON on stdin and returns ranked memory ids.
PATHMARK_HYBRID_CANDIDATES	500	Maximum candidates sent to the optional reranker.
PATHMARK_RETRIEVAL_TIMEOUT_MS	30000	Timeout for the optional reranker.
PATHMARK_EXPORT_KEY	unset	Passphrase for AES-256-GCM portable exports/imports. Never returned by get_config.
PATHMARK_INDEX_LOCK_TIMEOUT_MS	120000	Cross-process wait limit for index initialization or rebuild.

Synthesis Modes

Pathmark separates memory from reasoning.

client

Default. The MCP server returns relevant memory context, and your MCP client model synthesizes the answer. This works across Codex, Claude Desktop, Cursor, and any other MCP client without giving Pathmark a model credential.

PATHMARK_SYNTHESIS_PROVIDER=client pathmark

command

Use any local subscription or model CLI that accepts a prompt on stdin and writes an answer to stdout:

PATHMARK_SYNTHESIS_PROVIDER=command \
PATHMARK_CHAT_COMMAND="your-ai-cli --model your-model" \
pathmark

This is the general path for users with another paid subscription CLI or a local model runner.

codex

Use the proven Codex CLI bridge. It runs a controlled, non-interactive codex exec turn with hooks and memories disabled to avoid recursion:

PATHMARK_SYNTHESIS_PROVIDER=codex \
PATHMARK_CODEX_MODEL=gpt-5.5 \
pathmark

This is useful for Codex users who have persisted ChatGPT/Codex CLI auth locally but do not want to add an OpenAI API key. Pathmark sends the synthesis prompt through stdin, runs Codex in an empty temporary workspace, ignores project rules, and exposes only a minimal environment. Memory records are treated as untrusted data rather than executable instructions.

openai-compatible

Use any provider that exposes /chat/completions, including many Kimi, GLM/Z.ai, OpenRouter, LiteLLM, Ollama-compatible gateways, and self-hosted routers:

PATHMARK_SYNTHESIS_PROVIDER=openai-compatible \
PATHMARK_OPENAI_BASE_URL=https://api.provider.example/v1 \
PATHMARK_OPENAI_API_KEY=... \
PATHMARK_OPENAI_MODEL=... \
pathmark

This mode only affects ask_memory. Regular MCP tools still store and retrieve local memory without a model provider.

Setup CLI

pathmark setup <client> prints copy-paste setup for common harnesses. Add --json when you want structured output for scripts.

Supported targets:

codex
claude-code
claude-desktop
cursor
opencode
gemini-cli
generic
openai-compatible
command

Aliases include claude, gemini, kimi, glm, and z-ai.

Gemini CLI setup includes portable SessionStart, BeforeAgent, AfterTool, and AfterAgent hooks for automatic scoped recall and capture. Other harnesses can feed exported transcripts through the generic ingestion surface:

pathmark ingest --client=claude-code --namespace=my-project < transcript.json
pathmark ingest --client=opencode --namespace=my-project < transcript.json

Store maintenance and portable sync

Maintenance commands preview destructive changes unless --apply is present:

pathmark doctor
pathmark compact
pathmark compact --apply --retention-days=90
pathmark purge --namespace=old-client
pathmark purge --namespace=old-client --apply

Applied compaction and purge create a backup before replacing the canonical file. Soft deletion remains available through delete_memory; hard purge physically removes selected records from JSONL and rebuilds the derived index.

Use scoped exports and merge imports as the transport-neutral sync layer:

pathmark export --namespace=my-project --output=project.jsonl
pathmark import project.jsonl --namespace=my-project

For an encrypted portable bundle, configure the passphrase outside the command line:

PATHMARK_EXPORT_KEY='use-a-secret-manager' pathmark export --encrypted --output=project.pathmark
PATHMARK_EXPORT_KEY='use-a-secret-manager' pathmark import project.pathmark

Pathmark does not silently upload these files. Move them through a trusted filesystem, backup tool, or sync provider of your choice.

Optional hybrid retrieval

Default retrieval stays local SQLite FTS. To enable semantic or embedding-backed reranking without forcing a model dependency, set PATHMARK_RERANK_COMMAND to a trusted local command. It receives one JSON object on stdin containing query and candidates, and must return a JSON array of ranked record ids (or { "ids": [...] }). If it fails or times out, Pathmark falls back to lexical results.

Data Format

Pathmark stores newline-delimited JSON at:

~/.pathmark/memory/memory.jsonl

memory.jsonl remains the canonical source of truth. Pathmark also maintains a derived, disposable search index at memory.index.sqlite. The index is rebuilt automatically when the JSONL file changes outside Pathmark, and it can be deleted safely while Pathmark is stopped.

Each record is inspectable:

{
  "id": "uuid",
  "kind": "memory",
  "text": "The user prefers local-first tools.",
  "tags": ["preference"],
  "source": "mcp",
  "createdAt": "2026-06-29T00:00:00.000Z",
  "updatedAt": "2026-06-29T00:00:00.000Z"
}

Deletes are soft deletes by default: the record gets a deletedAt timestamp. Use preview-first purge_memory or pathmark purge --apply for physical erasure. Updates preserve up to 50 prior versions, superseded records link to their replacement, and expired records are excluded from recall.

Malformed JSONL lines are skipped rather than crashing every tool. pathmark codex status reports their count as invalidRecordCount so the source file can be repaired deliberately.

Roadmap

• Provider presets for common local AI CLIs where stable commands exist.
• Encrypted store option.
• Hosted sync as an opt-in layer, not a requirement.
• Native auto-capture packages for additional harness plugin systems beyond Codex and Gemini CLI.
• Example recipes for Codex, Claude Desktop, Cursor, ChatGPT, and local LLM tools.

Positioning

Pathmark gives your agents a shared working memory that stays on your machine.

Switch agents. Keep the context.

Bring your own subscription. Keep your memory local.

License

MIT