{
  "markdown": "<div align=\"center\">\n\n<img src=\"https://raw.githubusercontent.com/scarletkc/Perenna/main/assets/logo.svg\" alt=\"Perenna logo\" width=\"160\" />\n\n# Perenna\n\n[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/downloads/)\n[![PyPI](https://img.shields.io/pypi/v/perenna.svg)](https://pypi.org/project/perenna/)\n[![CI](https://img.shields.io/github/actions/workflow/status/scarletkc/Perenna/validate.yml?branch=main)](https://github.com/scarletkc/Perenna/actions/workflows/validate.yml)\n[![Codecov](https://img.shields.io/codecov/c/github/scarletkc/Perenna/main)](https://codecov.io/github/scarletkc/Perenna)\n[![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/scarletkc/Perenna?utm_source=oss&utm_medium=github&utm_campaign=scarletkc%2FPerenna&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)](https://coderabbit.ai)\n[![License](https://img.shields.io/github/license/scarletkc/Perenna.svg)](https://github.com/scarletkc/Perenna/blob/main/LICENSE)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/scarletkc/Perenna)\n[![perenna MCP server](https://glama.ai/mcp/servers/scarletkc/perenna/badges/score.svg)](https://glama.ai/mcp/servers/scarletkc/perenna)\n\n</div>\n\n<!-- mcp-name: io.github.scarletkc/perenna -->\n\n---\n\nA lightweight, Git-backed permanent memory for AI agents. Claude Code, Codex,\nChatGPT, Cursor, and other MCP clients can share durable memories without\nsharing a vendor account or conversation history.\n\n- Separate MCP tools for reading, writing, and deleting memories\n- Local stdio, loopback-only Streamable HTTP, and OAuth-protected remote HTTP\n- Human-readable Markdown stored in an independent Git repository\n- Local Vexor retrieval index that can always be rebuilt from Git\n- Cross-process locking for multiple local agent processes\n\n## Why Perenna?\n\nYour memory should follow **you**, not the agent you happen to be using.\n\nClaude Code, Codex, Cursor, and ChatGPT keep memory in separate silos. Switch\nagents and your memory disappears. Switch machines and local memory stays\nbehind.\n\nPerenna gives them one **shared, Git-backed memory**. Local agents and ChatGPT\ncan connect to the same self-hosted Perenna service, while every durable memory\nstays ordinary Markdown you can inspect, edit, version, and back up yourself.\n\nPerenna stays focused on permanent memory: no required account, proprietary\nmemory cloud, or automatic conversation extraction.\n\n## Quickstart\n\n### Install with your AI agent\n\nPaste this into Claude Code, Codex, ChatGPT Desktop, Cursor, or another coding\nagent with terminal and local MCP configuration access:\n\n```text\nOpen the following URL, read the complete instructions, and follow them to\ninstall and connect Perenna:\nhttps://raw.githubusercontent.com/scarletkc/Perenna/main/docs/guides/agent-installation.md\n```\n\n### Install a published release\n\nPerenna requires Python 3.12+, Git, and\n[uv](https://docs.astral.sh/uv/).\n\n#### Install Perenna\n\n```bash\nuv tool install perenna\n```\n\n#### Configure retrieval\n\nPerenna needs a working Vexor embedding provider. For interactive provider\nselection and configuration, run:\n\n```bash\nuvx vexor init\n```\n\nPerenna automatically reuses `~/.vexor/config.json`. When using process-level\nconfiguration, make sure the MCP server receives `VEXOR_CONFIG_JSON` plus\n`VEXOR_API_KEY` or the selected provider's key from its host environment.\nRemote providers receive memory text and search queries.\n\nIf you choose local embeddings, also install Perenna's local extra:\n\n```bash\nuv tool install \"perenna[local]\"\n```\n\n[Vexor provider configuration](https://github.com/scarletkc/Perenna/blob/main/docs/reference/configuration.md#vexor-provider-configuration)\ncovers remote and local setup. From the environment that starts the MCP client,\nverify the selected provider with:\n\n```bash\nuvx vexor doctor\n```\n\n#### Connect a client\n\nFor the standalone setup, configure the MCP client to start:\n\n```text\nperenna mcp\n```\n\nFollow the\n[Client setup guide](https://github.com/scarletkc/Perenna/blob/main/docs/guides/client-setup.md)\nfor the exact client command or configuration file.\n\nCodex and Claude Code can also install the optional memory behavior Skill:\n\n```bash\nperenna skill install --agent codex\n# or\nperenna skill install --agent claude-code\n```\n\nRepeat `--agent` in one command when both clients should receive the skill.\nThe [configuration reference](https://github.com/scarletkc/Perenna/blob/main/docs/reference/configuration.md#bundled-agent-skill)\ndocuments user and project scope, destinations, and replacement safeguards.\n\nCodex and Claude Code can instead install the combined Skill and MCP connection\nfrom Perenna's repository Marketplace. Follow the\n[Plugin setup guide](https://github.com/scarletkc/Perenna/blob/main/docs/guides/plugin-setup.md)\nand choose one setup path per client.\n\nPerenna creates its local data under `~/.perenna/` unless another home is\nconfigured.\n\n#### Add optional Git synchronization\n\nTo import, publish, or fast-forward compatible history through a private Git\nrepository, run:\n\n```bash\nperenna sync setup <repository-url>\n```\n\nSuccessful setup saves the selected remote in the Perenna home. Use\n`perenna sync disable` to return to saved local-only mode without removing the\nGit remote.\n\nThe\n[configuration reference](https://github.com/scarletkc/Perenna/blob/main/docs/reference/configuration.md#git-remote-synchronization)\nowns remote selection, credentials, conflict handling, and recovery details.\n\n### Install from source\n\n```bash\ngit clone https://github.com/scarletkc/Perenna.git\ncd Perenna\nuv tool install .\n```\n\nSource contributors should use the locked environment in the\n[development guide](https://github.com/scarletkc/Perenna/blob/main/docs/development/contributing.md#set-up-the-repository).\n\n## Documentation\n\nStart with the\n[documentation index](https://github.com/scarletkc/Perenna/blob/main/docs/index.md),\nthen follow the path for your task:\n\n- [Getting started](https://github.com/scarletkc/Perenna/blob/main/docs/getting-started.md)\n- [Client setup](https://github.com/scarletkc/Perenna/blob/main/docs/guides/client-setup.md)\n- [Plugin setup](https://github.com/scarletkc/Perenna/blob/main/docs/guides/plugin-setup.md)\n- [Secure MCP Tunnel](https://github.com/scarletkc/Perenna/blob/main/docs/guides/secure-mcp-tunnel.md)\n- [Self-hosting for ChatGPT](https://github.com/scarletkc/Perenna/blob/main/docs/guides/self-hosting.md)\n- [Using permanent memory](https://github.com/scarletkc/Perenna/blob/main/docs/guides/using-memory.md)\n- [`perenna-memory` Agent Skill](https://github.com/scarletkc/Perenna/blob/main/skills/perenna-memory)\n- [Configuration reference](https://github.com/scarletkc/Perenna/blob/main/docs/reference/configuration.md)\n- [Architecture](https://github.com/scarletkc/Perenna/blob/main/docs/concepts/architecture.md)\n- [Development guide](https://github.com/scarletkc/Perenna/blob/main/docs/development/contributing.md)\n\n## License\n\n[MIT](https://github.com/scarletkc/Perenna/blob/main/LICENSE)\n",
  "bytes": 7065,
  "sha": "2261e22cbb32798921643c9a36546ba2d024fae0b908911fca805b68c34bf0ae",
  "repo_slug": "scarletkc/perenna",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_scarletkc_perenna_48a6a684/readme"
}