Provides a local-first intent and provenance layer to share decisions, constraints, and preferences across different AI coding agents.
Also known as hacksurvivor/pathmark
- Stars
- 4
- Tools
- 25
- Downloads, 30 days
- —
- Latest version
- 0.1.17
- Last commit
- Oct 19, 2026
- License
- MIT
What is Pathmark MCP?
Pathmark provides a local-first intent and provenance layer to share decisions, constraints, and preferences across different AI coding agents. It exposes 25 tools, such as get_config, remember, create_conclusion.
Summary generated from the project's README
About Pathmark MCP server
Developers working across multiple AI coding tools can use Pathmark to maintain a consistent layer of intent and decision history. Instead of losing context when switching from Codex to Claude Code or Gemini CLI, this server provides a shared local storage for constraints, preferences, and approved conclusions. It functions as a provider-neutral bus that sits below your various agents to ensure that what one tool learns, others can recall.
The system operates entirely locally using a JSONL store located at ~/.pathmark/memory/memory.jsonl, meaning no accounts, API keys, or cloud backends are required. It is compatible with any MCP-capable harness including Cursor, opencode, and Claude Desktop. Users can manage their knowledge base through specific tools like remember for raw evidence, create_conclusion for durable preferences, and search_memory for retrieving past decisions. This setup ensures that your architectural decisions and coding preferences remain accessible regardless of which specific AI agent you are currently prompting.
What you can do with it
- 1Share context between different agentsYou can carry decisions made in Codex over to Claude Code without manually pasting recaps.
- 2Maintain a durable knowledge baseStore high-signal conclusions and preferences that require approval before being used for future tasks.
- 3Audit AI agent behaviorReview a chronological trail of prompts and memory injections to understand how an agent reached a conclusion.
- 4Automate Claude Code permissionsConfigure read-only tools to run in auto mode without constant permission prompts.
Written from the project's README. Every use case is checked against a quote from it.
How to install Pathmark MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Pathmark MCP in Claude Code
$ claude mcp add pathmark -- npx -y pathmarkInstall Pathmark MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"pathmark": {
"command": "npx",
"args": [
"-y",
"pathmark"
]
}
}
}Install Pathmark MCP in VS Code
.vscode/mcp.json
{
"servers": {
"pathmark": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"pathmark"
]
}
}
}Install Pathmark MCP in VS Code CLI
$ code --add-mcp '{"name":"pathmark","type":"stdio","command":"npx","args":["-y","pathmark"]}'Install Pathmark MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"pathmark": {
"command": "npx",
"args": [
"-y",
"pathmark"
]
}
}
}Install Pathmark MCP in Codex
$ codex mcp add pathmark -- npx -y pathmarkInstall Pathmark MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.pathmark] command = "npx" args = ["-y", "pathmark"]
Install Pathmark MCP in Gemini CLI
$ gemini mcp add -s user pathmark npx -- -y pathmarkInstall Pathmark MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"pathmark": {
"command": "npx",
"args": [
"-y",
"pathmark"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for pathmark 0.1.17 in an isolated container with no network and no keys. It answered and listed 25 tools.
Pathmark MCP tools 25
Read from the server with tools/listget_configRead-onlyShow the local Pathmark Memory store location and enabled optional features.
rememberActionSave raw searchable evidence. Durable intent should use the approval-gated conclusion workflow.
create_conclusionActionPropose a durable higher-signal conclusion. Approval is required by default before it can be recalled.
search_memoryRead-onlySearch saved local memories and conclusions.
get_contextRead-onlyReturn compact local memory context for a task or question.
recall_memoryRead-onlyTransparent recall for any MCP-capable harness. Use this at task start or before answering to show exactly which memories were used.
session_traceRead-onlyShow a bounded chronological audit trail for one captured session: prompts, exact injected memory IDs, redacted tool inputs/results, and answers.
rate_recallActionAttach explicit relevance labels to one exact Pathmark recall so audit_memory can report measured precision.
list_conclusionsRead-onlyList saved durable conclusions.
list_pending_conclusionsRead-onlyList bounded approval-gated conclusion proposals. Pending records are never returned by normal memory search.
approve_conclusionActionApprove one pending conclusion, optionally correcting its text or tags. The transition is atomic and auditable.
reject_conclusionActionReject one pending conclusion while retaining it in the canonical audit trail and excluding it from recall.
| get_config | Show the local Pathmark Memory store location and enabled optional features. | Read-only |
| remember | Save raw searchable evidence. Durable intent should use the approval-gated conclusion workflow. | Action |
| create_conclusion | Propose a durable higher-signal conclusion. Approval is required by default before it can be recalled. | Action |
| search_memory | Search saved local memories and conclusions. | Read-only |
| get_context | Return compact local memory context for a task or question. | Read-only |
| recall_memory | Transparent recall for any MCP-capable harness. Use this at task start or before answering to show exactly which memories were used. | Read-only |
| session_trace | Show a bounded chronological audit trail for one captured session: prompts, exact injected memory IDs, redacted tool inputs/results, and answers. | Read-only |
| rate_recall | Attach explicit relevance labels to one exact Pathmark recall so audit_memory can report measured precision. | Action |
| list_conclusions | List saved durable conclusions. | Read-only |
| list_pending_conclusions | List bounded approval-gated conclusion proposals. Pending records are never returned by normal memory search. | Read-only |
| approve_conclusion | Approve one pending conclusion, optionally correcting its text or tags. The transition is atomic and auditable. | Action |
| reject_conclusion | Reject one pending conclusion while retaining it in the canonical audit trail and excluding it from recall. | Action |
Show all 25 toolsShow fewer tools
get_memory_snapshotRead-onlyGenerate a bounded USER/PROJECT/AGENT snapshot from approved canonical conclusions only.
delete_memoryActionSoft-delete a saved memory or conclusion by id.
update_memoryActionCorrect an existing memory while preserving its prior versions in local history.
supersede_memoryActionReplace an outdated memory with a linked current record while preserving history.
purge_memoryActionPreview or permanently remove matching records from the canonical store. A backup is created before an applied purge.
consolidate_memoryActionPrepare a bounded unsynthesized evidence batch and, when server synthesis is configured, preview or stage evidence-backed conclusion proposals. Proposals are never auto-approved.
audit_memoryRead-onlyMeasure capture-to-recall behavior, unused records, recall age, duplicate rate, stale raw hits, and available precision evidence without changing memory.
doctor_memoryRead-onlyReport duplicate, deleted, expired, conclusion, invalid-record, and index health counts without changing data.
compact_memoryActionPreview or apply exact deduplication, expired-record removal, retention, and deleted-record purging. Applied runs create a backup.
backup_memoryActionCreate a point-in-time copy of the canonical local JSONL store.
export_memoryActionExport a scoped, mergeable JSONL bundle for another Pathmark installation or trusted sync transport.
ask_memoryRead-onlyAsk approved conclusions first, then scoped or explicitly requested raw evidence. Returns an answer, exact provenance, and a recallId for feedback.
chatRead-onlyChat with Pathmark using approved conclusions first and only scoped or explicitly requested raw fallback. Returns an answer, provenance, and recallId.
| get_memory_snapshot | Generate a bounded USER/PROJECT/AGENT snapshot from approved canonical conclusions only. | Read-only |
| delete_memory | Soft-delete a saved memory or conclusion by id. | Action |
| update_memory | Correct an existing memory while preserving its prior versions in local history. | Action |
| supersede_memory | Replace an outdated memory with a linked current record while preserving history. | Action |
| purge_memory | Preview or permanently remove matching records from the canonical store. A backup is created before an applied purge. | Action |
| consolidate_memory | Prepare a bounded unsynthesized evidence batch and, when server synthesis is configured, preview or stage evidence-backed conclusion proposals. Proposals are never auto-approved. | Action |
| audit_memory | Measure capture-to-recall behavior, unused records, recall age, duplicate rate, stale raw hits, and available precision evidence without changing memory. | Read-only |
| doctor_memory | Report duplicate, deleted, expired, conclusion, invalid-record, and index health counts without changing data. | Read-only |
| compact_memory | Preview or apply exact deduplication, expired-record removal, retention, and deleted-record purging. Applied runs create a backup. | Action |
| backup_memory | Create a point-in-time copy of the canonical local JSONL store. | Action |
| export_memory | Export a scoped, mergeable JSONL bundle for another Pathmark installation or trusted sync transport. | Action |
| ask_memory | Ask approved conclusions first, then scoped or explicitly requested raw evidence. Returns an answer, exact provenance, and a recallId for feedback. | Read-only |
| chat | Chat with Pathmark using approved conclusions first and only scoped or explicitly requested raw fallback. Returns an answer, provenance, and recallId. | Read-only |
Configuration
PATHMARK_CHAT_COMMANDPATHMARK_CODEX_MODELPATHMARK_EXPORT_KEYPATHMARK_OPENAI_API_KEYPATHMARK_OPENAI_BASE_URLPATHMARK_OPENAI_MODELPATHMARK_STORE_DIRPATHMARK_SYNTHESIS_PROVIDER
| Name | Description | |
|---|---|---|
| PATHMARK_CHAT_COMMAND | — | |
| PATHMARK_CODEX_MODEL | — | |
| PATHMARK_EXPORT_KEY | — | |
| PATHMARK_OPENAI_API_KEY | — | |
| PATHMARK_OPENAI_BASE_URL | — | |
| PATHMARK_OPENAI_MODEL | — | |
| PATHMARK_STORE_DIR | — | |
| PATHMARK_SYNTHESIS_PROVIDER | — |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubPathmark
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-permissionsadds 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/openWorldHintannotations, 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-firstchat/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:
| Tool | Purpose |
|---|---|
remember |
Save raw searchable evidence. Raw evidence is not treated as durable approved intent. |
create_conclusion |
Propose a higher-signal durable conclusion or preference. Approval is required by default before recall. |
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. |
rate_recall |
Label exact IDs from a chat / ask_memory recall as relevant or irrelevant so audit precision is measured. |
get_context |
Return compact context for a task or question. |
list_conclusions |
List approved saved conclusions. |
list_pending_conclusions |
Review bounded, paginated pending conclusion proposals. |
approve_conclusion |
Atomically approve a proposal, optionally correcting text/tags and recording the reviewer. |
reject_conclusion |
Retain a rejected proposal in the audit trail while permanently excluding it from recall. |
get_memory_snapshot |
Generate a bounded USER/PROJECT/AGENT snapshot from approved canonical conclusions. |
consolidate_memory |
Review a bounded unsynthesized evidence batch and optionally stage evidence-backed proposals. Nothing is auto-approved. |
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. |
audit_memory |
Measure capture-to-recall behavior, unused records, recall age, duplicates, stale raw hits, and whether precision labels exist. |
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 an approved-conclusion answer or scoped raw context, exact provenance, and a recall ID for feedback. |
chat |
Chat-compatible alias for ask_memory, including multi-intent conclusion retrieval and explicit abstention. |
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 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 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 generates one bounded USER/PROJECT/AGENT snapshot from approved canonical conclusions and does not inject raw session history;
- each non-trivial user prompt searches approved workspace/project conclusions first, then approved global or explicitly named-project conclusions;
- only when no approved conclusion matches, at most two raw records from the current workspace/project/session may be injected as a high-confidence fallback;
- raw fallback records must be within the separate automatic-recall horizon, 30 days by default; the full raw archive remains available to explicit
search_memoryandrecall_memorycalls; - raw cross-project history is never injected automatically; promote durable cross-project intent through the approval workflow;
- broad cross-project history remains available through explicit
search_memory/recall_memorycalls without silently entering every prompt; - matching memory is injected quietly by default, without adding a raw
recall_memorytool result to the conversation; - set
PATHMARK_CODEX_VISIBLE_RECALL=onwhen debugging or auditing to make Codex callrecall_memorywith the exact pre-capture result IDs and workspace tag; this explicit mode omits the redundant fullrecordscopy; - legacy transport envelopes and assistant progress updates are excluded from session-start and proactive relevance results, while realtime delegation envelopes retain only their current
<input>payload; - records containing Pathmark boundary escapes, instruction-override patterns, or invisible Unicode controls are tagged
memory-quarantinedand excluded from automatic recall; injected previews are escaped and explicitly treated as untrusted historical data; - no matching memory means no extra context is injected.
Durable extraction is approval-gated by default. create_conclusion creates a pending proposal; pending and rejected conclusions stay in the canonical JSONL audit trail but are structurally excluded from normal search, exact-ID recall, prompt injection, and snapshots. Use list_pending_conclusions, then approve_conclusion or reject_conclusion. Conclusions created before this workflow are treated as already approved for backward compatibility. Raw remember records remain searchable evidence and are not promoted automatically.
The session snapshot is generated from the same canonical store rather than maintained as a second flat file. It is frozen in the session-start hook output; prompt-time scoped recall remains dynamic.
Set PATHMARK_CODEX_PROACTIVE_RECALL=off if you want Codex hooks to capture memory but stop prompt-time recall.
Set PATHMARK_CODEX_VISIBLE_RECALL=on only when you want an explicit audit/debug recall_memory tool call. Proactive prompt-time recall remains active when this is off.
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. |
PATHMARK_CODEX_VISIBLE_RECALL |
off |
Opt into an audit/debug recall_memory tool call that exposes exact usedMemories. Proactive memory injection remains active when this is off. |
PATHMARK_CODEX_CAPTURE_TOOL_OUTPUTS |
off |
Store bounded redacted tool-output previews. Output hashes, status, duration, and exit codes remain available when this is off. |
PATHMARK_CODEX_MEMORY_SNAPSHOT |
on |
Generate a bounded approved-conclusion snapshot at Codex session start/resume. |
PATHMARK_SNAPSHOT_CHARS |
4000 |
Character budget for generated snapshots; clamped to 500–12000. |
PATHMARK_CODEX_RAW_RECALL_DAYS |
30 |
Prompt-time eligibility horizon for raw evidence. 0 disables automatic raw fallback without deleting or hiding explicit search results. |
PATHMARK_CODEX_RAW_RECALL_LIMIT |
2 |
Maximum fresh raw records injected when no approved conclusion matches. Clamped to 0–2. |
PATHMARK_CODEX_PROACTIVE_CONSOLIDATION |
on |
At session start, nudge Codex to review a bounded evidence batch when scoped raw history is accumulating without conclusions. |
PATHMARK_CONSOLIDATION_MIN_EVIDENCE |
8 |
Minimum unsynthesized user/assistant records before the proactive consolidation nudge appears. |
PATHMARK_CONCLUSION_APPROVAL |
on |
Stage new conclusions for explicit approval. Set off only for trusted legacy automation. |
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_ACTIVITY_RETENTION_DAYS |
30 |
Automatic lifetime for recall/tool activity records; 0 disables age-based activity expiry. |
PATHMARK_ACTIVITY_MAX_RECORDS |
5000 |
Physical cap for activity records; oldest activity is removed automatically. 0 disables the count cap. |
PATHMARK_RERANK_COMMAND |
unset | Optional trusted local embedding/vector or hybrid reranker. Strict kind/tag/namespace filters are applied before candidates leave the store; the command 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 affects MCP ask_memory / chat and CLI pathmark chat. 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
Pathmark MCP questions
How do I add Pathmark MCP to Claude Code?
Run claude mcp add pathmark -- npx -y pathmark in your terminal. Add --scope user to make it available in every project.
How do I add Pathmark MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Pathmark MCP provide?
It exposes 25 tools, including get_config, remember, create_conclusion, search_memory, get_context.
Do I need an account or cloud database to use Pathmark?
No, Pathmark is local-first and does not require an account, hosted database, API key, or vendor backend.
Where is my context stored?
Your context is stored locally on your disk at ~/.pathmark/memory/memory.jsonl.
Can Pathmark work with Claude Code without constant permission prompts?
Yes, using the setup command with the --apply-permissions flag adds allow rules for read-only tools so they run without prompts.
What happens if I want to delete memory?
You can perform a soft-delete of a memory or conclusion by its ID, or use the purge tool for permanent deletion.