Skip to content
Palimem Docsspec v1.7.0

Configuration

This page documents environment variables, data directory conventions, and the operator CLI. Harness-specific config (MCP JSON, TOML, plugin config) lives on the integration pages.

Environment variables

Section titled “Environment variables”

Core

Section titled “Core”
Variable Default Purpose
MEMORY_SERVICE_DATA_DIR .ai-memory/data SQLite data directory (relative to CWD unless absolute)
MEMORY_SERVICE_NAMESPACE workspace folder name Default namespace for session scope
MEMORY_SERVICE_PYTHON python3 (Linux/macOS) / py -3 (Windows) Python interpreter for hook CLIs

Hook debugging

Section titled “Hook debugging”
Variable Default Purpose
MEMORY_SERVICE_HOOK_DEBUG unset Set to 1 to log hook ingest counts to stderr
MEMORY_SERVICE_BLOCK_AUTO_COMPACT unset Set to 1 to veto Claude Code auto-compact
MEMORY_SERVICE_COMPACTION_SAFE_FILE unset Path to safe-file for auto-compact veto

SessionEnd consolidation

Section titled “SessionEnd consolidation”
Variable Default Purpose
MEMORY_SERVICE_RUN_CONSOLIDATION_ON_SESSION_END unset Set to 1 to consolidate at Claude Code session end
MEMORY_SERVICE_REVIEW_EXPORT_PATH unset Path for consolidation review export

Governance

Section titled “Governance”
Variable Default Purpose
MEMORY_SERVICE_RETENTION_SESSION_DAYS 90 Days to retain session-scope episodes
MEMORY_SERVICE_RETENTION_BELIEF_DAYS 365 Days to retain unconfirmed beliefs
MEMORY_SERVICE_RETENTION_NOTE_DAYS 30 Days to retain low-salience notes
MEMORY_SERVICE_PII_SCAN_ENABLED unset Set to 1 to enable PII pre-store scanning
MEMORY_SERVICE_PII_SCAN_NAMESPACE unset Namespace to apply PII scanning to

Data directory

Section titled “Data directory”

The data directory contains:

.ai-memory/data/
├── memory.db          ← SQLite database (WAL + semantic units)
├── memory.db-wal      ← SQLite WAL journal
└── memory.db-shm      ← SQLite shared memory

Backup: Copy the .ai-memory/data/ directory. The SQLite WAL files must be included.

Migration: The .ai-memory/ prefix will become .palimem/ in a future version. Both paths resolve to the same store during the migration window via a symlink or config alias.

Multiple projects: Use separate MEMORY_SERVICE_DATA_DIR values for different projects, or use namespace isolation within one data directory.

Operator CLI (ai-memory)

Section titled “Operator CLI (ai-memory)”

The ai-memory operator CLI at app/scripts/ai-memory.js provides management commands:

Terminal window
node app/scripts/ai-memory.js <command> [options]

connect <harness>

Section titled “connect <harness>”

Write MCP config for a harness:

Terminal window
node .../ai-memory.js connect cursor --project-root "$(pwd)" --data-dir .ai-memory/data
node .../ai-memory.js connect windsurf --project-root "$(pwd)" --data-dir .ai-memory/data
node .../ai-memory.js connect copilot --project-root "$(pwd)" --data-dir .ai-memory/data
node .../ai-memory.js connect codex --project-root "$(pwd)" --data-dir .ai-memory/data

Common flags: --replace, --dry-run, --project-root, --data-dir.

review export

Section titled “review export”

Generate a human-readable review report:

Terminal window
node .../ai-memory.js review export \
  --data-dir .ai-memory/data \
  --output .ai-memory/review.md

consolidate

Section titled “consolidate”

Deduplicate and summarize memory:

Terminal window
node .../ai-memory.js consolidate \
  --data-dir .ai-memory/data \
  --dry-run          # preview only
  --export-review .ai-memory/review.md

MCP server entrypoints

Section titled “MCP server entrypoints”
Entrypoint Language Use
app/scripts/memory-service-mcp.js Node.js Default MCP stdio server
app/run_production_stdio_server.py Python Python-direct MCP stdio server

Use the Node.js wrapper for harnesses that expect a Node-based server. Use the Python server directly when Node.js is unavailable or for Docker-based deployments.

Hook CLIs

Section titled “Hook CLIs”
CLI Purpose
app/hook_remember.py Write hook — called by SessionStart, Stop, PreCompact
app/hook_search.py Search hook — called by SessionStart for manifest assembly

These CLIs do not require the MCP server to be running.

Data migration

Section titled “Data migration”

From .ai-memory/data to .palimem/data

Section titled “From .ai-memory/data to .palimem/data”

When the rename ships, run:

Terminal window
mv .ai-memory .palimem
export MEMORY_SERVICE_DATA_DIR=.palimem/data

Or set an alias in your shell profile. The underlying SQLite schema is unchanged.

From file-based memory (MEMORY.md, USER.md)

Section titled “From file-based memory (MEMORY.md, USER.md)”

Use import_markdown.py:

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

Next steps

Section titled “Next steps”