Pathmark Memory

Local-first memory for MCP clients.

Pathmark Memory gives agent tools a shared, durable memory without requiring a hosted account, a vector database, or an API key. It runs as a standard Model Context Protocol server, so the same local memory can be used from Codex, Claude Code, opencode, Gemini CLI, OpenClaw, Hermes Agent, Grok-compatible MCP clients, Cursor, Claude Desktop, and other tools that can launch stdio MCP servers.

Why this exists

Most agent memory systems are tied to one product, one hosted backend, or one subscription. Pathmark is intentionally small:

• Local JSONL store by default.

• Standard MCP tools instead of a proprietary client.

• Works when the model lives in the MCP client.

• Optional subscription CLI bridge for server-side synthesis.

• Optional OpenAI-compatible API bridge for Kimi, GLM, OpenRouter, local gateways, and other compatible providers.

• Easy to inspect, back up, delete, or migrate.

Pathmark is provider-neutral. Codex is one optional synthesis preset, but the core server works with any MCP client that can use local tools.

Related MCP server: auxly-memory-cli

Tools

Pathmark exposes these MCP tools:

Quick Start

npm install -g github:hacksurvivor/pathmark

Then add the MCP server to your client.

The npm package name pathmark is currently available, but this first release is GitHub-only until npm publishing is explicitly done.

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

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 run build
npm run smoke

Run directly:

PATHMARK_STORE_DIR=.pathmark npm run dev

Configuration

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 ChatGPT/Codex subscription auth locally but do not want to add an OpenAI API key.

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.

Data Format

Pathmark stores newline-delimited JSON at:

~/.pathmark/memory/memory.jsonl

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: the record gets a deletedAt timestamp.

Roadmap

• Codex installer for hooks, capture, and nudge behavior.

• Provider presets for common local AI CLIs where stable commands exist.

• Import/export commands for other memory systems.

• Better ranking with optional local embeddings.

• Namespaces for projects, teams, and clients.

• Encrypted store option.

• Hosted sync as an opt-in layer, not a requirement.

• Example recipes for Codex, Claude Desktop, Cursor, ChatGPT, and local LLM tools.

Positioning

Pathmark is not trying to be a full agent platform. It is the memory layer: a small MCP server that gives agents a persistent working memory the user owns.

The public hook is simple:

Bring your own subscription. Keep your memory local.

License

MIT