Agent Memory

English · Português · हिन्दी · עברית

Agent Memory keeps what Claude Code learns as Markdown files on your computer. It shows those notes as a graph and gives them back to Claude Code through an MCP server.

Until v0.4 the app was called Memória. Since v0.5 the names are in English too: the agent-memory command, the agent-memory MCP server with the memory_search, memory_add and memory_related tools, and the ~/.agent-memory folder. The old names still work (see Coming from v0.4).

• Lessons, rules (do, don't) and task history.

• Each note can be linked to a ticket (Jira, GitHub) and its epic.

• Fast search (SQLite FTS5) by name, project, ticket, epic, tags and text.

• A window with the graph, filters, a timeline, a form for new notes and Claude's MCP activity.

• In English, Portuguese, Hindi and Hebrew.

• Everything stays on your computer. Nothing is sent anywhere.

Install

No administrator rights needed.

macOS (Intel and Apple Silicon) and Linux, in Terminal:

curl -fsSL https://github.com/cx-guilherme-pinto/claude-memory-app/releases/download/v0.5.0/install.sh | sh

Windows 10/11, in PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://github.com/cx-guilherme-pinto/claude-memory-app/releases/download/v0.5.0/install.ps1 | iex"

The installer:

1. installs uv (pinned version) if it's missing;

2. downloads the wheel and constraints.txt and checks their SHA-256;

3. installs the app with the uv-managed Python 3.12;

4. on Windows, installs the WebView2 Runtime (per user) if it's missing;

5. creates a shortcut: ~/Applications/Agent Memory.app on Mac, "Agent Memory" in the Start menu on Windows.

The commands go to ~/.local/bin (Mac/Linux) or %USERPROFILE%\.local\bin (Windows).

Portable version (no install)

Every release also has one zip per platform, with Python inside:

Unzip and open. No admin rights and no network needed. The workshop setup does this for you.

• Connect it to Claude Code: selftest prints the right claude mcp add command. On Mac, …/Memoria.app/Contents/MacOS/memoria selftest (the portable app keeps its old file name and shows as Agent Memory); on Windows, agent-memory.cmd selftest. After the one-line install, it's just agent-memory selftest.

• Prefer the one-line install command. A zip downloaded in a browser needs approval in System Settings → Privacy & Security: macOS blocks the app because it isn't signed. To unblock it in Terminal: xattr -dr com.apple.quarantine ~/Applications/Memoria.app. On Windows, at "Windows protected your PC", click "More info" and then "Run anyway".

• Once it's connected to Claude Code, don't move the app.

• The zips, the app folder and its launchers keep the Memoria name: older portable copies can still update in place.

Details and decisions: docs/portatil.md.

Related MCP server: claude-brain

Connect to Claude Code

claude mcp add --scope user agent-memory -- "$HOME/.local/bin/agent-memory" mcp

On Windows: claude mcp add --scope user agent-memory -- "%USERPROFILE%\.local\bin\agent-memory.exe" mcp.

MCP tools (in Claude Code: mcp__agent-memory__memory_search and so on):

type is lesson, do, dont or history. Results use the same English names: {"total": 1, "results": [{"id", "path", "type", "title", "project", "task", "epic", "url", "tags", "files", "date", "cost_usd", "links", "excerpt", "score"}]} (memory_related adds strength and reasons, for example {"link": 1, "task": 1}). Empty fields are left out.

Use

In the window, click a node to see the note. Press / to search and Esc to close. Search shows memories, projects and tasks/epics; pick one to focus it. Filters choose the project, epic, task and period. The type list filters the map. The timeline's play button shows the graph growing.

On Windows, if WebView2 is missing, the interface opens in the browser at 127.0.0.1. The terminal prints the session address (http://127.0.0.1:<port>/?t=<key>). The key is local and only works while the app is open.

Claude activity

The Claude activity button at the top of the column shows what Claude asked Agent Memory for over MCP:

• four numbers: calls today, total calls, calls per minute (average of the last 10 minutes) and memories recalled (unique);

• the last 100 recalled memories, with time, tool, title, project and task. A search with no results also shows up, with what was searched. Click a title to open the memory.

The view refreshes on its own. It isn't split by session.

The log lives in ~/.agent-memory/.index/activity.sqlite, on your computer, separate from the index (agent-memory reindex keeps it). The searched text goes through the same secret redaction and is cut short. Note contents are never logged. Old rows are dropped automatically; the total call count is kept.

Languages

The app speaks English, Portuguese, Hindi and Hebrew. By default it follows the system language:

• macOS: the first supported language in System Settings › General › Language & Region;

• Windows: the Windows display language;

• others: LANGUAGE, LC_ALL, LC_MESSAGES or LANG.

If none is supported, it uses English. The picker at the top of the column switches the language at once and saves it in ~/.agent-memory/preferences.json. From the command line: agent-memory language he. The AGENT_MEMORY_LANG variable overrides everything.

• Hebrew opens right to left. Each note's text keeps its own direction.

• Hindi and Hebrew use Noto Sans Devanagari and Noto Sans Hebrew, bundled with the app.

• Technical terms stay in English in every language (MCP, token, ticket, tool names).

Where memories live

In ~/.agent-memory (or the folder set in AGENT_MEMORY_HOME):

~/.agent-memory/
  <project>/<YYYY-MM-DD>-<slug>.md   one note per file
  config.json                        update URLs (optional)
  .index/index-v3.sqlite             index; safe to delete
  .index/activity.sqlite             MCP call log ("Claude activity" view)
  preferences.json                   language chosen in the picker

Each note has a YAML header. The field names are part of the contract:

---
type: lesson           # lesson | do | dont | history
title: Use the build cache
project: security-arena
task: ARENA-12         # optional: ticket key (or owner/repo#12)
epic: ARENA-1          # optional: epic or parent
url: https://company.atlassian.net/browse/ARENA-12   # optional
tags: [ci, cache]      # optional
files: [orchestrator/plan.mjs]
date: '2026-10-16T13:25:33+01:00'
cost_usd: 1.25         # optional
links: [Avoid retries]
---

The build is 3x faster with the cache. See [[Avoid retries]].

You can edit the files by hand. The app picks up the changes. agent-memory reindex rebuilds the index at any time. epic, url and tags came in v0.2 and are optional: v0.1 notes are still valid.

Tickets:

• Jira keys are upper-cased (abc-123 → ABC-123); GitHub keys look like owner/repo#12.

• Without task, the app takes it from url when it's a Jira ticket or an issue/PR.

• A note without epic inherits its task's epic, if another note names it.

• Searching ABC-123 finds that task's notes, its epic's notes and notes that mention it.

Link strength, strongest first: explicit link ([[...]] or links), same task, same epic, same project, shared files.

Coming from v0.4

Nothing moves and nothing is rewritten. The old names keep working:

To use the new MCP name in Claude Code: claude mcp remove --scope user memoria, then the claude mcp add above.

Update

agent-memory update

1. Finds the latest version with git ls-remote --tags (no API).

2. Downloads the wheel and constraints.txt and checks SHA256SUMS.

3. Reinstalls with uv tool install --force.

4. Rebuilds the index. It never touches your notes.

On Windows, the install finishes in a new window. Close Claude Code first.

In the portable version, update downloads the new zip, checks it and swaps the app folder in place. The connection to Claude Code keeps working.

URLs come from ~/.agent-memory/config.json and, if missing, from the package's release.conf. Keys read (an environment variable with the same name overrides them):

Privacy

• Notes, the index and the interface stay on your computer.

• Before saving, the app redacts tokens, API keys (sk-ant-…, ghp_…, AKIA…, xox…), JWTs, private keys and patterns like password=….

• The interface only listens on 127.0.0.1, with a random session key.

• The only network use is the version check (git ls-remote) and agent-memory update. To turn it off: AGENT_MEMORY_NO_UPDATE=1.

• No embeddings and no models. Search is plain text (SQLite FTS5).

Troubleshooting

• "This Python's SQLite has no FTS5": reinstall with uv's Python (uv tool install --force --managed-python --python 3.12 <wheel>).

• Company proxy: uv and agent-memory update use HTTPS_PROXY and the system certificates. For uv, also set UV_SYSTEM_CERTS=1.

• The window doesn't open: agent-memory --browser opens the same interface in the browser.

• "The search index of your memories is damaged": the app rebuilds the index from the notes by itself. If the message stays (on Windows, another process still has the file open), close Claude Code and the app, then run agent-memory reindex. The notes are never touched.

• "Warning: memory skipped": a note the app can't read (an error in the YAML header, not UTF-8, outside a project folder, a symlink to outside the folder). Fix the file: the app picks it up by itself.

Development

You need uv and Node.js 22 or newer.

uv sync
(cd web && npm ci && npm run build) && rm -rf src/memoria/web_dist && cp -R web/dist src/memoria/web_dist
uv run playwright install chromium
uv run pytest

• scripts/build.sh: UI, wheel, installers, portable zips and SHA256SUMS in dist/.

• scripts/build_portatil.py: the portable zips (PORTATIL=0 scripts/build.sh skips them).

• scripts/publish-release.sh: tag, release and assets. Calls to the hosting API live only in create_release() (Gitea or GitHub, from RELEASE_PROVIDER).

• scripts/mudar-alojamento.sh: changes the hosting and the version in one go.

• scripts/lock.sh: regenerates constraints.txt and checks there are wheels for Mac and Windows.

• release.conf: the single source of URLs and versions.

Instructions for Claude: CLAUDE.md. Status, risks and how to publish: docs/HANDOVER.md. Versions follow SemVer. See the CHANGELOG.

License

MIT. See LICENSE. The Bricolage Grotesque, Noto Sans Devanagari and Noto Sans Hebrew fonts ship with the interface under the SIL Open Font License 1.1 (web/public/fonts/).