Perenna: shared agent memory on Git
Perenna
Lightweight permanent agent memory on Git: Claude Code, Codex, Cursor and ChatGPT read and write the same Markdown notes
- 60 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The agent writes and deletes memories in a Git repository, and they return into the context of every connected agent
- With a remote embedding provider memory text and queries go to an external service
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/perennaDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The agent writes and deletes memories in a Git repository, and they return into the context of every connected agent
- With a remote embedding provider memory text and queries go to an external service
This is third-party code. Review the repository files before installing.
What it does
Perenna stores agent long-term memories as ordinary Markdown files in a separate Git repository. The memory belongs to you and not to a specific agent: Claude Code, Codex, Cursor and ChatGPT connect to one service and share it without a common vendor account. The files can be read, edited, versioned and copied by yourself. The MCP server has separate tools for reading, writing and deleting memories. Transports are local stdio, loopback-only Streamable HTTP and remote HTTP protected by OAuth for a self-hosted service. Cross-process locking lets several local agents work at once. Search runs over a local Vexor index that can always be rebuilt from Git. There is no automatic extraction of memories from conversations: writes happen by an explicit agent action. For Codex and Claude Code an optional skill carries rules for handling memory, and the perenna sync setup command enables synchronization with a private Git repository.
Who it is for. People who work with several agents and want one portable memory that is visible, editable and stored as an ordinary Git repository.
Good fit when
- You switch between Claude Code, Codex and Cursor and do not want to re-explain preferences
- Agent memory should live in Markdown so you can read and edit it by hand
- Memory should move between machines through a private Git repository
- ChatGPT and local agents should connect to one self-hosted service
- You want a change history for memory with the ability to roll back a note
Not a fit when
- You want automatic summaries of conversations: Perenna writes only what the agent saved explicitly
- You have no embedding provider: search does not work without a configured Vexor
- You want ready cloud memory with an account and support: the project is built for self-hosting
Example request
Remember that I prefer short commits in Conventional Commits style and recall it in the next session in another agent.MCP
- Transport
- stdio, http
- Authentication
- OAuth
Environment variables
VEXOR_API_KEYsecret- Vexor embedding provider key
PERENNA_GIT_REMOTE- Private Git repository URL for synchronization
Limitations
Python 3.12 or newer, Git and the uv manager are required. Search needs a working Vexor embedding provider: the uvx vexor init command helps configure it, and remote providers receive memory text and search queries. Local embeddings install with the perenna[local] variant. Synchronization needs a private Git repository and credentials for it. Remote HTTP with OAuth needs self-deployment and hardening. The latest version at check time was 0.4.1, the project is young and interfaces may change.
How to disable. Remove the perenna entry from the MCP client config and run uv tool uninstall perenna. The ~/.perenna data folder and the Git repository of notes remain, delete them by hand if the memory is no longer needed.
FAQ
Where does the memory live?
In ordinary Markdown files in a separate Git repository inside the Perenna home, ~/.perenna by default. You can read, edit, version and back them up like any files.
How do I install Perenna?
With uv tool install perenna, then search is configured through uvx vexor init and the client launches perenna mcp. You can give the agent the agent-installation.md link and it does it itself.
Which transports are there?
Local stdio, loopback-only Streamable HTTP and remote HTTP protected by OAuth. The remote variant is for connecting ChatGPT to your own service.
What goes to the embedding provider?
With a remote provider, memory texts and search queries are sent there. If that is unwanted, install perenna[local] and compute embeddings on your device.
How do I sync between machines?
With perenna sync setup and the address of a private Git repository. The perenna sync disable command turns sync off while the remote stays.
Discussion
No questions or reviews yet.
Related
MCP serversPiia Engram: portable memory for AI agents
Piia Engram
Local memory about you and your projects: Claude Code, Codex and Cursor read the same preferences and lessons from your disk
Agent memory as a graph of linked facts: decisions and errors outlive the session, with no vector database or paid API calls
Local memory for AI agents in plain Markdown files: it keeps only what you approve and serves it through MCP
Persistent memory for coding agents: insights are stored as markdown cards and recalled at the start of the next session.
Self-hosted long-term memory for agents: semantic search, a knowledge graph and autonomous consolidation over MCP and a REST API
Persistent agent memory in a folder of linked markdown notes, so Claude Code remembers a project across sessions
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Perenna: shared agent memory on Git (this card) | no | OAuth | 60 | |
| MCP Memory Keeper | no | not required | 136 | context storage between sessions without Git or shared access for several agents |
| Agent Memory Engine | no | not required | 127 | a memory engine without a shared Git repository and OAuth for remote clients |
README in short
The README describes the idea of shared memory with no vendor lock-in, a quick start with installation through an agent or by hand, Vexor setup, client connection, skills for Codex and Claude Code, Git synchronization and installation from source.