{
"markdown": "# Pathmark\n\nCarry intent across agents without turning stale code facts into hidden memory.\n\n
\n \n \n \n \n
\n\n## What's New — v0.1.15\n\nPathmark v0.1.15 keeps proactive memory useful without making the conversation noisy:\n\n- relevant memory is still injected automatically before Codex answers;\n- raw `recall_memory` tool output is now hidden by default, keeping the chat focused on the answer instead of memory plumbing;\n- `PATHMARK_CODEX_VISIBLE_RECALL=on` restores the explicit recall trace whenever you want to audit which records were used;\n- vulnerable transitive `fast-uri` and `qs` versions are replaced by patched releases in the published dependency lock.\n\nSee the [v0.1.15 release notes](docs/releases/v0.1.15.md) or the complete [changelog](CHANGELOG.md). The npm badge above always shows the currently published version.\n\n
\n \n
\n\nPathmark 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.\n\n**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.\n\nYour context stays on disk at `~/.pathmark/memory/memory.jsonl`. You do not need an account, hosted database, API key, or vendor backend to start.\n\n## OpenAI Build Week 2026\n\nPathmark 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.\n\nDuring 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:\n\n- fixed a reproduced multi-process SQLite index race;\n- added revision history, superseding, expiration, retention, diagnostics, backup, compaction, and preview-first hard purge;\n- added namespace-scoped reads and writes plus default secret redaction;\n- added scoped import/export, optional AES-256-GCM portable exports, local hybrid reranking, and portable harness ingestion;\n- hardened CI and npm delivery with required CodeQL and dependency review, immutable Action pins, protected tags, OpenSSF analysis, and SLSA provenance.\n\nThe 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`.\n\nSee the [Build Week implementation record](docs/build-week-2026.md) for the before/after boundary, commit evidence, Codex collaboration details, and a fast judge test.\n\n## Why Pathmark\n\nYou 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.\n\nPathmark gives those tools one place to read and write intent and evidence:\n\n- One local JSONL store across harnesses.\n- Standard MCP tools include `remember`, `search_memory`, `recall_memory`, `session_trace`, `rate_recall`, `consolidate_memory`, `audit_memory`, and conclusion-first `chat` / `ask_memory`.\n- Client-side synthesis by default, so your coding agent reads the context and answers.\n- Optional Codex CLI, local command, and OpenAI-compatible synthesis modes.\n- Plain files you can inspect, back up, delete, or migrate.\n\nPathmark stays provider-neutral. Codex gets one optional synthesis preset. The core server works with any MCP client that can use local tools.\n\nPathmark requires Node.js 22.5 or newer.\n\n## Cross-Harness Memory\n\nYou switch tools during a coding session:\n\n- Codex fixes the failing test.\n- Claude Code reviews the patch.\n- opencode cleans the diff.\n- Gemini CLI challenges the approach.\n\nPathmark keeps the notes in one store.\n\nPoint each harness at the same store:\n\n```text\nCodex \\\nClaude Code \\\nopencode > Pathmark MCP > ~/.pathmark/memory/memory.jsonl\nGemini CLI /\nCursor /\n```\n\nInstall 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`.\n\nPathmark sits below the agents as an intent, evidence, and provenance bus for your coding workflow.\n\n## Tools\n\nPathmark exposes these MCP tools:\n\n| Tool | Purpose |\n| --- | --- |\n| `remember` | Save raw searchable evidence. Raw evidence is not treated as durable approved intent. |\n| `create_conclusion` | Propose a higher-signal durable conclusion or preference. Approval is required by default before recall. |\n| `search_memory` | Search memories and conclusions. |\n| `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. |\n| `session_trace` | Return a bounded chronological audit trail for one session: prompts, exact injected memory IDs, redacted tool inputs/results, and answers. |\n| `rate_recall` | Label exact IDs from a `chat` / `ask_memory` recall as relevant or irrelevant so audit precision is measured. |\n| `get_context` | Return compact context for a task or question. |\n| `list_conclusions` | List approved saved conclusions. |\n| `list_pending_conclusions` | Review bounded, paginated pending conclusion proposals. |\n| `approve_conclusion` | Atomically approve a proposal, optionally correcting text/tags and recording the reviewer. |\n| `reject_conclusion` | Retain a rejected proposal in the audit trail while permanently excluding it from recall. |\n| `get_memory_snapshot` | Generate a bounded USER/PROJECT/AGENT snapshot from approved canonical conclusions. |\n| `consolidate_memory` | Review a bounded unsynthesized evidence batch and optionally stage evidence-backed proposals. Nothing is auto-approved. |\n| `delete_memory` | Soft-delete a memory or conclusion by id. |\n| `update_memory` | Correct a record while preserving prior versions. |\n| `supersede_memory` | Replace an outdated record with a linked current record. |\n| `purge_memory` | Preview or apply permanent deletion by id, namespace, tags, source, or date. |\n| `audit_memory` | Measure capture-to-recall behavior, unused records, recall age, duplicates, stale raw hits, and whether precision labels exist. |\n| `doctor_memory` | Report duplicates, deleted/expired records, conclusions, and index health. |\n| `compact_memory` | Preview or apply deduplication, retention, and physical cleanup with an automatic backup. |\n| `backup_memory` | Create a point-in-time canonical JSONL backup. |\n| `export_memory` | Export a scoped mergeable JSONL bundle, optionally encrypted. |\n| `ask_memory` | Return an approved-conclusion answer or scoped raw context, exact provenance, and a recall ID for feedback. |\n| `chat` | Chat-compatible alias for `ask_memory`, including multi-intent conclusion retrieval and explicit abstention. |\n| `get_config` | Show local store configuration. |\n\n## Quick Start\n\n```bash\nnpm install -g pathmark\n```\n\nThen add the MCP server to your client.\n\nPrefer npm for normal installs. To test the current GitHub `main` branch directly:\n\n```bash\nnpm install -g --install-links=true github:hacksurvivor/pathmark\n```\n\nGenerate a setup snippet for your harness:\n\n```bash\npathmark setup list\npathmark setup claude-code\npathmark setup opencode --json\npathmark setup gemini-cli\npathmark setup kimi\n```\n\nSee [docs/compatibility.md](docs/compatibility.md) for Codex, Claude Code, opencode, Gemini CLI, OpenClaw, Hermes Agent, Grok CLI, Kimi, GLM, and generic MCP setups.\n\n### Codex\n\n```bash\ncodex mcp add pathmark -- pathmark\n```\n\nCodex users can also enable auto-capture:\n\n```bash\npathmark codex install --replace-legacy-hooks\n```\n\nWhen 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.\n\n### Claude Code\n\n```bash\nclaude mcp add pathmark -- pathmark\n```\n\n### opencode / Gemini CLI\n\nUse the generated snippets:\n\n```bash\npathmark setup opencode\npathmark setup gemini-cli\n```\n\n### Claude Desktop\n\nAdd this to your Claude Desktop MCP config:\n\n```json\n{\n \"mcpServers\": {\n \"pathmark\": {\n \"command\": \"pathmark\",\n \"env\": {\n \"PATHMARK_STORE_DIR\": \"~/.pathmark/memory\"\n }\n }\n }\n}\n```\n\n### Cursor\n\nAdd the same command to Cursor's MCP server settings:\n\n```json\n{\n \"mcpServers\": {\n \"pathmark\": {\n \"command\": \"pathmark\"\n }\n }\n}\n```\n\n## Local Development\n\n```bash\nnpm install\nnpm test\nnpm run coverage\n```\n\nRun directly:\n\n```bash\nPATHMARK_STORE_DIR=.pathmark npm run dev\n```\n\n## Import Legacy Memory\n\nPathmark can import a compatible local JSONL memory store without deleting or moving the source files.\n\n```bash\nnpm run import:legacy -- --source-dir ~/old-codex-memory\n```\n\nDefaults:\n\n```text\nLegacy source: ~/.pathmark/legacy/codex\nPathmark target: ~/.pathmark/memory/memory.jsonl\n```\n\nThe 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.\nIt uses the same store lock as live MCP and Codex writers, so an import cannot overwrite records captured concurrently.\n\nUse a dry run first when migrating another machine:\n\n```bash\nnpm run import:legacy -- --source-dir ~/old-codex-memory --dry-run\n```\n\n## Codex Auto-Capture\n\nInstall Pathmark as the Codex memory adapter:\n\n```bash\npathmark codex install --replace-legacy-hooks\n```\n\nThis registers the Pathmark MCP server, enables Codex hooks, and removes old compatible hook commands from Codex. It does not delete or move memory files.\n\nThe Codex adapter is proactive by default:\n\n- user prompts, final assistant answers, and tool activity are captured locally; intermediate Codex commentary is excluded;\n- tool activity records include bounded redacted input previews and hashes, status, exit code, duration, and changed files when the hook provides them;\n- tool-output hashes are captured for correlation, while output text remains private by default and requires `PATHMARK_CODEX_CAPTURE_TOOL_OUTPUTS=on`;\n- activity records expire after 30 days and are physically capped at 5,000 records by default;\n- session start/resume generates one bounded USER/PROJECT/AGENT snapshot from approved canonical conclusions and does not inject raw session history;\n- each non-trivial user prompt searches approved workspace/project conclusions first, then approved global or explicitly named-project conclusions;\n- 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;\n- raw fallback records must be within the separate automatic-recall horizon, 30 days by default; the full raw archive remains available to explicit `search_memory` and `recall_memory` calls;\n- raw cross-project history is never injected automatically; promote durable cross-project intent through the approval workflow;\n- broad cross-project history remains available through explicit `search_memory` / `recall_memory` calls without silently entering every prompt;\n- matching memory is injected quietly by default, without adding a raw `recall_memory` tool result to the conversation;\n- set `PATHMARK_CODEX_VISIBLE_RECALL=on` when debugging or auditing to make Codex call `recall_memory` with the exact pre-capture result IDs and workspace tag; this explicit mode omits the redundant full `records` copy;\n- legacy transport envelopes and assistant progress updates are excluded from session-start and proactive relevance results, while realtime delegation envelopes retain only their current `` payload;\n- records containing Pathmark boundary escapes, instruction-override patterns, or invisible Unicode controls are tagged `memory-quarantined` and excluded from automatic recall; injected previews are escaped and explicitly treated as untrusted historical data;\n- no matching memory means no extra context is injected.\n\nDurable 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.\n\nThe 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.\n\nSet `PATHMARK_CODEX_PROACTIVE_RECALL=off` if you want Codex hooks to capture memory but stop prompt-time recall.\nSet `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.\n\n`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.\n\nUse `--replace-legacy-hooks` when you want Pathmark hooks to take over from earlier compatible hook commands. Without it, Pathmark installs alongside existing hook commands.\n\nCheck the adapter status:\n\n```bash\npathmark codex status\n```\n\nThe status output is JSON and includes Pathmark hook state, MCP registration state, legacy hook presence, the active store paths, and the current record count.\n\nRemove Pathmark hooks and MCP registration without deleting memory:\n\n```bash\npathmark codex uninstall\n```\n\n## Configuration\n\n| Variable | Default | Description |\n| --- | --- | --- |\n| `PATHMARK_STORE_DIR` | `~/.pathmark/memory` | Directory for `memory.jsonl`. |\n| `PATHMARK_MAX_SEARCH_RESULTS` | `12` | Default search limit. |\n| `PATHMARK_CODEX_PROACTIVE_RECALL` | `on` | Automatically inject relevant Pathmark context before non-trivial Codex prompts. Use `off` to capture without prompt-time recall. |\n| `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. |\n| `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. |\n| `PATHMARK_CODEX_MEMORY_SNAPSHOT` | `on` | Generate a bounded approved-conclusion snapshot at Codex session start/resume. |\n| `PATHMARK_SNAPSHOT_CHARS` | `4000` | Character budget for generated snapshots; clamped to 500–12000. |\n| `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. |\n| `PATHMARK_CODEX_RAW_RECALL_LIMIT` | `2` | Maximum fresh raw records injected when no approved conclusion matches. Clamped to 0–2. |\n| `PATHMARK_CODEX_PROACTIVE_CONSOLIDATION` | `on` | At session start, nudge Codex to review a bounded evidence batch when scoped raw history is accumulating without conclusions. |\n| `PATHMARK_CONSOLIDATION_MIN_EVIDENCE` | `8` | Minimum unsynthesized user/assistant records before the proactive consolidation nudge appears. |\n| `PATHMARK_CONCLUSION_APPROVAL` | `on` | Stage new conclusions for explicit approval. Set `off` only for trusted legacy automation. |\n| `PATHMARK_SYNTHESIS_PROVIDER` | `client` | `client`, `command`, `codex`, or `openai-compatible`. |\n| `PATHMARK_CHAT_COMMAND` | unset | Command provider: receives a synthesized prompt on stdin and writes an answer on stdout. |\n| `PATHMARK_CODEX_COMMAND` | `codex` | Codex provider command. |\n| `PATHMARK_CODEX_MODEL` | unset | Optional Codex model override. |\n| `PATHMARK_OPENAI_BASE_URL` | `https://api.openai.com/v1` | OpenAI-compatible API base URL. |\n| `PATHMARK_OPENAI_API_KEY` | unset | OpenAI-compatible API key. |\n| `PATHMARK_OPENAI_MODEL` | unset | Model id for OpenAI-compatible synthesis. |\n| `PATHMARK_CHAT_TIMEOUT_MS` | `120000` | Synthesis command timeout. |\n| `PATHMARK_NAMESPACE` | unset | Default namespace applied consistently to MCP reads and writes. |\n| `PATHMARK_REDACT_MCP_WRITES` | `on` | Redact common secret-shaped values on `remember`, conclusion, update, supersede, import, and ingest paths. |\n| `PATHMARK_RETENTION_DAYS` | `0` | Retention policy used by compaction; `0` disables age-based removal. Conclusions are retained. |\n| `PATHMARK_ACTIVITY_RETENTION_DAYS` | `30` | Automatic lifetime for recall/tool activity records; `0` disables age-based activity expiry. |\n| `PATHMARK_ACTIVITY_MAX_RECORDS` | `5000` | Physical cap for activity records; oldest activity is removed automatically. `0` disables the count cap. |\n| `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. |\n| `PATHMARK_HYBRID_CANDIDATES` | `500` | Maximum candidates sent to the optional reranker. |\n| `PATHMARK_RETRIEVAL_TIMEOUT_MS` | `30000` | Timeout for the optional reranker. |\n| `PATHMARK_EXPORT_KEY` | unset | Passphrase for AES-256-GCM portable exports/imports. Never returned by `get_config`. |\n| `PATHMARK_INDEX_LOCK_TIMEOUT_MS` | `120000` | Cross-process wait limit for index initialization or rebuild. |\n\n## Synthesis Modes\n\nPathmark separates memory from reasoning.\n\n### `client`\n\nDefault. 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.\n\n```bash\nPATHMARK_SYNTHESIS_PROVIDER=client pathmark\n```\n\n### `command`\n\nUse any local subscription or model CLI that accepts a prompt on stdin and writes an answer to stdout:\n\n```bash\nPATHMARK_SYNTHESIS_PROVIDER=command \\\nPATHMARK_CHAT_COMMAND=\"your-ai-cli --model your-model\" \\\npathmark\n```\n\nThis is the general path for users with another paid subscription CLI or a local model runner.\n\n### `codex`\n\nUse the proven Codex CLI bridge. It runs a controlled, non-interactive `codex exec` turn with hooks and memories disabled to avoid recursion:\n\n```bash\nPATHMARK_SYNTHESIS_PROVIDER=codex \\\nPATHMARK_CODEX_MODEL=gpt-5.5 \\\npathmark\n```\n\nThis 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.\n\n### `openai-compatible`\n\nUse any provider that exposes `/chat/completions`, including many Kimi, GLM/Z.ai, OpenRouter, LiteLLM, Ollama-compatible gateways, and self-hosted routers:\n\n```bash\nPATHMARK_SYNTHESIS_PROVIDER=openai-compatible \\\nPATHMARK_OPENAI_BASE_URL=https://api.provider.example/v1 \\\nPATHMARK_OPENAI_API_KEY=... \\\nPATHMARK_OPENAI_MODEL=... \\\npathmark\n```\n\nThis mode affects MCP `ask_memory` / `chat` and CLI `pathmark chat`. Regular MCP tools still store and retrieve local memory without a model provider.\n\n## Setup CLI\n\n`pathmark setup ` prints copy-paste setup for common harnesses. Add `--json` when you want structured output for scripts.\n\nSupported targets:\n\n```text\ncodex\nclaude-code\nclaude-desktop\ncursor\nopencode\ngemini-cli\ngeneric\nopenai-compatible\ncommand\n```\n\nAliases include `claude`, `gemini`, `kimi`, `glm`, and `z-ai`.\n\nGemini 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:\n\n```bash\npathmark ingest --client=claude-code --namespace=my-project < transcript.json\npathmark ingest --client=opencode --namespace=my-project < transcript.json\n```\n\n## Memory chat, consolidation, maintenance, and portable sync\n\nMaintenance commands preview destructive changes unless `--apply` is present:\n\n```bash\npathmark chat \"What did we decide about release signing?\" --namespace=my-project\npathmark consolidate --namespace=my-project\npathmark consolidate --namespace=my-project --cursor=LAST_RECORD_ID\nPATHMARK_SYNTHESIS_PROVIDER=codex pathmark consolidate --namespace=my-project --apply\npathmark feedback --recall-id=RECALL_ID --relevant=MEMORY_ID --irrelevant=OTHER_ID\npathmark audit --days=30\npathmark audit --namespace=my-project --days=90\npathmark doctor\npathmark compact\npathmark compact --apply --retention-days=90\npathmark purge --namespace=old-client\npathmark purge --namespace=old-client --apply\n```\n\n`pathmark chat` and the MCP `chat` / `ask_memory` tools search approved conclusions first. Multi-intent questions can return separate conclusions for separate clauses. In default client mode, approved conclusions produce a safe extractive `answer`; a configured `codex`, `command`, or `openai-compatible` provider can synthesize richer prose. Raw fallback requires an explicit scope (`--namespace` / tags) or `kind: memory`, preventing unscoped cross-workspace history from entering chat.\n\nEvery matched chat query records recall activity and returns a `recallId` when the store is writable. Abstentions and read-only stores return `recallId: null`. Use MCP `rate_recall` or `pathmark feedback` with exact recalled IDs to label relevance. `pathmark audit` reports `precision.status: \"labeled\"`, measured precision, and label coverage once feedback exists.\n\n`pathmark consolidate` is preview-first. With default client synthesis it returns the bounded evidence and exact instructions for the host agent, which can call `create_conclusion` with supporting `evidenceIds`. When more eligible evidence remains, the result includes `nextCursor` and `remainingAfterBatch`; pass the cursor to review the next stable page. With a configured server-side synthesis provider, it previews structured candidates; `--apply` stages them as pending conclusions for `approve_conclusion` or `reject_conclusion`. It never auto-approves extracted intent.\n\nApplied 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.\n\n`pathmark audit` is read-only. It separates all raw records from consolidation-eligible user/assistant evidence, then reports capture-to-recall ratio, actionable synthesis backlog, recall age, exact duplicates, stale raw hits, and scope/missing-reference signals. Precision remains `unlabeled` until explicit feedback exists; Pathmark never substitutes a heuristic for a user label.\n\nUse scoped exports and merge imports as the transport-neutral sync layer:\n\n```bash\npathmark export --namespace=my-project --output=project.jsonl\npathmark import project.jsonl --namespace=my-project\n```\n\nFor an encrypted portable bundle, configure the passphrase outside the command line:\n\n```bash\nPATHMARK_EXPORT_KEY='use-a-secret-manager' pathmark export --encrypted --output=project.pathmark\nPATHMARK_EXPORT_KEY='use-a-secret-manager' pathmark import project.pathmark\n```\n\nPathmark does not silently upload these files. Move them through a trusted filesystem, backup tool, or sync provider of your choice.\n\n## Optional hybrid retrieval\n\nDefault 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.\n\n## Data Format\n\nPathmark stores newline-delimited JSON at:\n\n```text\n~/.pathmark/memory/memory.jsonl\n```\n\n`memory.jsonl` remains the canonical source of truth. Pathmark also maintains a derived, disposable search index at `memory.index.v5.sqlite`. Index filenames are schema-versioned so old and new MCP processes can coexist during a rolling restart. The index is rebuilt automatically when the JSONL file changes outside Pathmark, and inactive index versions can be deleted safely after their processes stop.\n\nEach record is inspectable:\n\n```json\n{\n \"id\": \"uuid\",\n \"kind\": \"memory\",\n \"text\": \"The user prefers local-first tools.\",\n \"tags\": [\"preference\"],\n \"source\": \"mcp\",\n \"createdAt\": \"2026-06-29T00:00:00.000Z\",\n \"updatedAt\": \"2026-06-29T00:00:00.000Z\"\n}\n```\n\nDeletes 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. The raw automatic-recall horizon is separate from storage retention: evidence can age out of proactive injection while remaining explicitly searchable.\n\nMalformed 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.\n\n## Roadmap\n\n- Provider presets for common local AI CLIs where stable commands exist.\n- Encrypted store option.\n- Hosted sync as an opt-in layer, not a requirement.\n- Native auto-capture packages for additional harness plugin systems beyond Codex and Gemini CLI.\n- Example recipes for Codex, Claude Desktop, Cursor, ChatGPT, and local LLM tools.\n\n## Positioning\n\nPathmark gives your agents a shared working memory that stays on your machine.\n\n> Switch agents. Keep the context.\n\n> Bring your own subscription. Keep your memory local.\n\n## Author and citation\n\nPathmark is created and maintained by [Sergey Moloman](https://rflxai.com/founder/sergey-moloman), a B2B AI integration specialist and private AI contractor, and founder of [RFLX AI](https://rflxai.com/).\n\nMachine-readable authorship and citation metadata are available in [`CITATION.cff`](CITATION.cff) and [`codemeta.json`](codemeta.json).\n\n## License\n\nMIT\n",
"bytes": 28377,
"sha": "5558c391fbd433b56625cdf06d2a9aede5e0e73d92a13e0e412734b3a4b696b0",
"repo_slug": "hacksurvivor/pathmark",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_hacksurvivor_pathmark_db647444/readme"
}
![\"current](\"https://img.shields.io/npm/v/pathmark?label=version\")
\n ![\"npm](\"https://img.shields.io/npm/dt/pathmark?label=npm%20downloads\")
\n ![\"weekly](\"https://img.shields.io/npm/dw/pathmark?label=weekly%20downloads\")
\n ![\"Pathmark](\"https://raw.githubusercontent.com/hacksurvivor/pathmark/main/assets/pathmark-hero.png\")
\n