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 tutorial walks you through connecting Palimem to Claude Code in under five minutes.

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”
  • Python 3.13+ and Node.js 18+ installed
  • Repository cloned: git clone https://github.com/palimem/palimem
  • Claude Code installed (see Claude Code docs)

Install

Section titled “Install”

  1. Clone and install Node dependencies

    Terminal window
    git clone https://github.com/palimem/palimem
    cd palimem
    cd app
    npm install
    cd ..

  2. Copy the MCP config to your project

    Copy .mcp.json from the Claude Code example to your project root:

    Terminal window
    cp examples/claude-code/.mcp.json .

    This registers the memory-service MCP server using stdio transport. Claude Code picks it up automatically on next start.

  3. Enable lifecycle hooks (recommended)

    Merge the hooks pack into your Claude Code settings:

    Terminal window
    cp examples/claude-code/hooks.json \
      .claude/hooks.json

    The hooks enable automatic memory capture at session start, on tool failure, and at session end.

  4. Set your data directory (optional)

    Palimem defaults to .ai-memory/data in your project root. To use a custom location:

    Terminal window
    export MEMORY_SERVICE_DATA_DIR=/path/to/your/memory/store

Verify

Section titled “Verify”

Start Claude Code in your project, then ask your agent:

  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 Claude Code chat to let the agent configure Palimem for you:

Install Palimem as governed local memory for this project.


- Project: Palimem (spec v1.7.0)
- Prefer: Claude Code plugin if available, else MCP stdio
- Data directory: .ai-memory/data (or .palimem/data after rename)
- Verify: tools/list shows 11 tools; memory_status reports ok and index current


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

Seed memory (optional)

Section titled “Seed memory (optional)”

Pre-load your user profile and project notes from Markdown files:

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”