Skip to content
Palimem Docsspec v1.7.0

Getting Started with Palimem

Palimem is governed, local-first memory for coding agents. It keeps facts current through supersession, routes context by scope, and preserves a full audit trail — all on your own disk. No cloud account required.

This guide gets you running in under five minutes. npm and the Claude Code plugin are the recommended paths — cloning the repository is optional for contributors and advanced setups.

What is Palimem?

Section titled “What is Palimem?”

Palimem stores agent memory as a layered structure — a palimpsest. Every write appends to an immutable log. Derived semantic units hold current truth. When facts change, new writes supersede old ones rather than silently overwriting history.

  • Write — Append to the write-ahead log; supersede on conflict
  • Derive — Current semantic units reflect truth on top
  • Recall — Scoped search (user / session / repository)
  • Audit — Point-in-time recall and export when you need proof

Before you begin

Section titled “Before you begin”

Install

Section titled “Install”

MCP harnesses — Cursor, Windsurf, Copilot CLI, Codex, VS Code, Gemini CLI. No clone required:

Terminal window
npx -y @palimem/mcp@latest ai-memory connect <harness> \
  --project-root "$(pwd)" \
  --launcher npx \
  --data-dir .ai-memory/data

Replace <harness> with cursor, windsurf, copilot, codex, vscode, or gemini.

--launcher npx writes MCP config with npx -y @palimem/mcp. See the matching integration page for harness-specific targets.

Run the MCP server directly:

Terminal window
npx -y @palimem/mcp@latest

Manual MCP config (npm) — if you prefer to hand-edit instead of using ai-memory connect:

{
  "mcpServers": {
    "memory-service": {
      "command": "npx",
      "args": ["-y", "@palimem/mcp"],
      "env": {
        "MEMORY_SERVICE_DATA_DIR": ".ai-memory/data"
      }
    }
  }
}

Verify

Section titled “Verify”

Ask your agent (in Claude Code, Cursor, or your connected harness):

  1. Call tools/list — expect 11 tools (including memory_query_temporal and memory_audit_export).
  2. Call memory_status with scope repository and your project namespace — expect ok: true and index_status.state: "current".

If tools/list shows 9 tools instead of 11, update to spec v1.7.0.

Agent prompt

Section titled “Agent prompt”

Paste this into your agent chat to configure Palimem:

Install Palimem as governed local memory for this project.


- Project: Palimem (spec v1.7.0)
- Prefer: Claude Code plugin if available, else npx -y @palimem/mcp@latest ai-memory connect <harness> --launcher npx
- Data directory: .ai-memory/data
- Verify: tools/list shows 11 tools; memory_status reports ok and index current


Use the install instructions at: https://palimem.com/docs/getting-started/#install
Do not enable cloud services unless I ask.

Seed memory (optional, clone path)

Section titled “Seed memory (optional, clone path)”

Pre-load your user profile and project notes from Markdown files (requires a cloned repository):

Terminal window
python3 app/import_markdown.py \
  --data-dir .ai-memory/data \
  examples/markdown/USER.md.sample \
  examples/markdown/MEMORY.md.sample

Next steps

Section titled “Next steps”