# Palimem

> Governed agent memory for coding agents. Local-first — supersession, scoped recall, and audit export.

Palimem is governed runtime memory over a spec-driven MCP server. Facts append to a write-ahead log; updates supersede prior values. Scoped recall separates user, session, and repository context. Install from npm (`@palimem/mcp`), Claude Code plugin, or source. Apache-2.0.

## Key concepts

- **Why governed memory** — Governed current state vs recall@k: /docs/concepts/why-governed-memory
- **Palimem and OKF** — Curated knowledge bundles vs runtime governed memory: /docs/concepts/palimem-and-okf
- **Supersession** — New writes supersede outdated values; history is preserved.
- **Scopes** — User, session, and repository contexts stay isolated.
- **Audit** — Point-in-time recall (`as_of`), retention controls, and export.
- **11 MCP tools** — Defined in spec v1.7.0 with automated validation.

## Spec

- Spec: v1.7.0 ([palimem/palimem `spec/README.md`](https://github.com/palimem/palimem/blob/main/spec/README.md))
- npm: [@palimem/mcp v1.7.2](https://www.npmjs.com/package/@palimem/mcp) (component metadata: 1.7.1)
- Release: v1.7.2 ([GitHub release](https://github.com/palimem/palimem/releases/tag/v1.7.2), [docs release notes](/docs/release-notes/v1.7.2)); spec v1.7.0 ([v1.7.0 notes](/docs/release-notes/v1.7.0))
- License: Apache-2.0
- Repository: https://github.com/palimem/palimem

## npx quick start

No clone required (Node.js 18+):

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

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

Fallback (GitHub specifier): `npx github:palimem/palimem ai-memory connect <harness> --project-root "$(pwd)" --launcher npx --data-dir .ai-memory/data`

## Editor integrations (spec v1.7.0)

Claude Code:
  /docs/integrations/claude-code
  Config: cp examples/claude-code/.mcp.json .

Claude Code plugin:
  /docs/integrations/claude-code-plugin
  Command: claude plugin marketplace add palimem/palimem && claude plugin install memory-service@palimem

Copilot CLI:
  /docs/integrations/copilot-cli
  Command (npx): npx @palimem/mcp ai-memory connect copilot --project-root "$(pwd)" --launcher npx --data-dir .ai-memory/data
  Command (clone): node app/scripts/ai-memory.js connect copilot --project-root "$(pwd)" --data-dir .ai-memory/data

Codex:
  /docs/integrations/codex
  Command (npx): npx @palimem/mcp ai-memory connect codex --project-root "$(pwd)" --launcher npx --data-dir .ai-memory/data
  Command (clone): node app/scripts/ai-memory.js connect codex --project-root "$(pwd)" --data-dir .ai-memory/data

Cursor:
  /docs/integrations/cursor
  Command (npx): npx @palimem/mcp ai-memory connect cursor --project-root "$(pwd)" --launcher npx --data-dir .ai-memory/data
  Command (clone): node app/scripts/ai-memory.js connect cursor --project-root "$(pwd)" --data-dir .ai-memory/data

Windsurf:
  /docs/integrations/windsurf
  Command (npx): npx @palimem/mcp ai-memory connect windsurf --project-root "$(pwd)" --launcher npx --data-dir .ai-memory/data
  Command (clone): node app/scripts/ai-memory.js connect windsurf --project-root "$(pwd)" --data-dir .ai-memory/data

VS Code + Copilot Agent:
  /docs/integrations/vscode-copilot-agent
  Command (npx): npx @palimem/mcp ai-memory connect vscode --project-root "$(pwd)" --launcher npx --data-dir .ai-memory/data
  Command (clone): node app/scripts/ai-memory.js connect vscode --project-root "$(pwd)" --data-dir .ai-memory/data

Copilot IDE:
  /docs/integrations/copilot-ide
  Command (npx): npx @palimem/mcp ai-memory connect vscode --project-root "$(pwd)" --launcher npx --data-dir .ai-memory/data
  Command (clone): node app/scripts/ai-memory.js connect vscode --project-root "$(pwd)" --data-dir .ai-memory/data

Gemini CLI:
  /docs/integrations/gemini-cli
  Command (npx): npx @palimem/mcp ai-memory connect gemini --project-root "$(pwd)" --launcher npx --data-dir .ai-memory/data
  Command (clone): node app/scripts/ai-memory.js connect gemini --project-root "$(pwd)" --data-dir .ai-memory/data

Hermes:
  /docs/integrations/hermes
  Command: python3 -m pip install -e adapters/hermes

OpenClaw:
  /docs/integrations/openclaw
  Plugin path: adapters/openclaw

## Agent setup prompt

```
Install Palimem as local memory for this project.

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

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

## Full docs index

/docs/llms.txt

## Discovery

- AI catalog: /.well-known/ai-catalog.json
- Documentation: https://palimem.com/docs/
- GitHub: https://github.com/palimem/palimem