Skip to content
Palimem Docsspec v1.7.0

Use Palimem with Claude Code

Connect Palimem to Claude Code using MCP stdio transport and the full lifecycle hooks pack. This is the primary recommended integration for v1.

Prerequisites

Section titled “Prerequisites”
  • Claude Code ≥ 1.0 with MCP support
  • Python 3.13+ and Node.js 18+
  • Repository cloned: git clone https://github.com/palimem/palimem
  • Node dependencies installed: cd app && npm install
Section titled “Recommended install”

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

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

Config block

Section titled “Config block”

The committed sample at examples/claude-code/.mcp.json:

{
  "mcpServers": {
    "memory-service": {
      "command": "node",
      "args": [
        "app/scripts/memory-service-mcp.js"
      ],
      "env": {
        "MEMORY_SERVICE_DATA_DIR": ".ai-memory/data"
      }
    }
  }
}

Adjust the args path to an absolute path if you run Claude Code from a different working directory.

Section titled “Enable lifecycle hooks (recommended)”

Palimem ships a full hooks pack for Claude Code that captures memory automatically at key session events.

Terminal window
cp examples/claude-code/hooks.json \
  .claude/hooks.json
Hook When What it does
SessionStart Session begins Exports a bounded Markdown memory manifest into context
PostToolUseFailure Bash command fails Writes a tool_failure episode to session scope
Stop Claude finishes a turn Backfills transcript errors; stores a turn summary fact
PreCompact Before /compact Flushes user snippets and custom instructions to repository facts
SessionEnd Session ends Optional consolidation (set MEMORY_SERVICE_RUN_CONSOLIDATION_ON_SESSION_END=1)

Verification

Section titled “Verification”

Start Claude Code in your project. Ask the agent to call tools/list (11 tools), then memory_status with scope repository and your project namespace (ok: true, index_status.state: "current").

Agent prompt

Section titled “Agent prompt”

Paste this into Claude Code to let the agent set up or verify Palimem for this project:

Set up Palimem as governed local memory for this Claude Code project.


- Project: Palimem (spec v1.7.0)
- MCP config: copy examples/claude-code/.mcp.json to project root
- Hooks: copy examples/claude-code/hooks.json to .claude/hooks.json
- Data directory: .ai-memory/data
- Verify: tools/list (11 tools), then memory_status — expect ok and index_status current


Do not enable cloud services.

Operator CLI

Section titled “Operator CLI”

The ai-memory operator CLI lets you review, consolidate, and export memory without starting a Claude Code session:

Terminal window
# Review staged consolidation proposals
node app/scripts/ai-memory.js review export \
  --data-dir .ai-memory/data \
  --output .ai-memory/review.md


# Run consolidation
node app/scripts/ai-memory.js consolidate \
  --data-dir .ai-memory/data \
  --export-review .ai-memory/review.md

Environment variables

Section titled “Environment variables”
Variable Default Purpose
MEMORY_SERVICE_DATA_DIR .ai-memory/data SQLite data directory
MEMORY_SERVICE_NAMESPACE workspace folder name Namespace for session scope
MEMORY_SERVICE_PYTHON python3 / py -3 Python for hook CLIs
MEMORY_SERVICE_HOOK_DEBUG unset Set to 1 to log hook ingest counts to stderr
MEMORY_SERVICE_RUN_CONSOLIDATION_ON_SESSION_END unset Set to 1 to consolidate at session end
MEMORY_SERVICE_BLOCK_AUTO_COMPACT unset Set to 1 to veto Claude Code auto-compact

Troubleshooting

Section titled “Troubleshooting”

MCP server not appearing in Claude Code

Claude Code reads .mcp.json on startup. Restart Claude Code after placing or modifying the file.

ENOENT error on memory-service-mcp.js

The Node wrapper is not installed. Run:

Terminal window
cd app && npm install

Tools show 9 instead of 11

You are on an older version of the memory service. Pull the latest main branch and restart. memory_query_temporal and memory_audit_export were added in spec v1.6.0.

Hooks not triggering

Verify that .claude/hooks.json is present in your project and that MEMORY_SERVICE_PYTHON points to Python 3.13+. Run python3 --version to check.

Session start manifest is empty

No memory has been stored yet. Store a fact via memory_remember, then restart the session.

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”