Perenna — MCP memory server for Claude Code and
A shared memory layer for AI agents: notes live as Markdown in a separate Git repo and stay reachable from several clients.
claude mcp add --env PERENNA_GIT_REMOTE=<PERENNA_GIT_REMOTE> --env VEXOR_API_KEY=<VEXOR_API_KEY> --env VEXOR_REMOTE_RERANK_API_KEY=<VEXOR_REMOTE_RERANK_API_KEY> --env VEXOR_CONFIG_JSON=<VEXOR_CONFIG_JSON> --transport stdio perenna -- uvx perennaWhat Perenna does
Perenna keeps an agent's long-term notes in a plain Git repository instead of a vendor cloud. Every memory is a Markdown file you can read, edit, diff or back up on your own. Reading, writing and deleting are split into separate MCP tools, so nothing drags a chat history along.
Retrieval runs through a local Vexor index that can be rebuilt from Git whenever you need. Several local agent processes are handled with cross-process locking. Transports cover local stdio, a loopback-only Streamable HTTP endpoint, and remote HTTP behind OAuth.
You need Python 3.12+, Git and uv before anything starts. Search stays dead until a Vexor embedding provider is configured: run uvx vexor init, then check it with uvx vexor doctor from the environment that launches the MCP client. Pick local embeddings and the install becomes perenna[local]. Local data sits under ~/.perenna/ unless you point it elsewhere.
What it helps with
- carry agent notes across different MCP clients
- share one memory store between Claude and Claude
- rebuild the search index from Git after it breaks
- sync memories between machines over a private repo
- hand-edit what the agent remembers in Markdown
Example prompts for the agent
- Save the auth scheme we settled on into memory
- Search memory for what we decided about database migrations
- Install the memory skill for Claude:
perenna skill install --agent codex
How to install Perenna
Platform CLI
claude mcp add --env PERENNA_GIT_REMOTE=<PERENNA_GIT_REMOTE> --env VEXOR_API_KEY=<VEXOR_API_KEY> --env VEXOR_REMOTE_RERANK_API_KEY=<VEXOR_REMOTE_RERANK_API_KEY> --env VEXOR_CONFIG_JSON=<VEXOR_CONFIG_JSON> --transport stdio perenna -- uvx perennaReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from perenna <command>
Platform CLI
codex mcp add perenna --env PERENNA_GIT_REMOTE=<PERENNA_GIT_REMOTE> --env VEXOR_API_KEY=<VEXOR_API_KEY> --env VEXOR_REMOTE_RERANK_API_KEY=<VEXOR_REMOTE_RERANK_API_KEY> --env VEXOR_CONFIG_JSON=<VEXOR_CONFIG_JSON> -- uvx perennaReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from perenna <command>
Config file
{
"mcpServers": {
"perenna": {
"command": "uvx",
"args": [
"perenna"
],
"env": {
"PERENNA_GIT_REMOTE": "<PERENNA_GIT_REMOTE>",
"VEXOR_API_KEY": "<VEXOR_API_KEY>",
"VEXOR_REMOTE_RERANK_API_KEY": "<VEXOR_REMOTE_RERANK_API_KEY>",
"VEXOR_CONFIG_JSON": "<VEXOR_CONFIG_JSON>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from perenna <command>
Config file
{
"servers": {
"perenna": {
"type": "stdio",
"command": "uvx",
"args": [
"perenna"
],
"env": {
"PERENNA_GIT_REMOTE": "<PERENNA_GIT_REMOTE>",
"VEXOR_API_KEY": "<VEXOR_API_KEY>",
"VEXOR_REMOTE_RERANK_API_KEY": "<VEXOR_REMOTE_RERANK_API_KEY>",
"VEXOR_CONFIG_JSON": "<VEXOR_CONFIG_JSON>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from perenna <command>
Platform CLI
gemini mcp add -e PERENNA_GIT_REMOTE=<PERENNA_GIT_REMOTE> -e VEXOR_API_KEY=<VEXOR_API_KEY> -e VEXOR_REMOTE_RERANK_API_KEY=<VEXOR_REMOTE_RERANK_API_KEY> -e VEXOR_CONFIG_JSON=<VEXOR_CONFIG_JSON> perenna uvx perennaReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from perenna <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Perenna
How do I install Perenna in Claude Code?
Install the package first with uv tool install perenna, then configure an embedding provider via uvx vexor init. Add the server with claude mcp add perenna -e VEXOR_API_KEY=<VEXOR_API_KEY> -e VEXOR_REMOTE_RERANK_API_KEY=<VEXOR_REMOTE_RERANK_API_KEY> -- uvx perenna.
What does Perenna do?
It gives agents permanent memory backed by a separate Git repository. Memories are Markdown files, and a local Vexor index handles search over them.
Can memories be synced between machines?
Yes, through a private Git repository: perenna sync setup <repository-url>. To go back to local-only mode without dropping the remote, run perenna sync disable.
