Memória

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

Memória 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.

• 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.4.1/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.4.1/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/Memória.app on Mac, "Memória" 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: memoria selftest prints the right claude mcp add command. On Mac, …/Memoria.app/Contents/MacOS/memoria selftest; on Windows, memoria.cmd 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.

Details and decisions: docs/portatil.md.

Related MCP server: ai-lab

Connect to Claude Code

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

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

MCP tools:

Tool and parameter names are in Portuguese and never change; their descriptions are in English.

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 Memória 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 ~/.memoria/.indice/registo.sqlite, on your computer, separate from the index (memoria 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 ~/.memoria/preferencias.json. From the command line: memoria lingua he. The MEMORIA_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 ~/.memoria (or the folder set in MEMORIA_HOME):

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

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

---
tipo: licao            # licao (lesson) | fazer (do) | nao_fazer (don't) | historico (history)
titulo: Use the build cache
projeto: arena-de-seguranca
tarefa: ARENA-12       # optional: ticket key (or owner/repo#12)
epico: ARENA-1         # optional: epic or parent
url: https://company.atlassian.net/browse/ARENA-12   # optional
etiquetas: [ci, cache] # optional: tags
ficheiros: [orquestrador/plan.mjs]
data: '2026-10-16T13:25:33+01:00'
custo_usd: 1.25        # optional
ligacoes: [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. memoria reindex rebuilds the index at any time. epico, url and etiquetas 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 tarefa, the app takes it from url when it's a Jira ticket or an issue/PR.

• A note without epico 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 ligacoes), same task, same epic, same project, shared files.

Update

memoria 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 ~/.memoria/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 memoria update. To turn it off: MEMORIA_SEM_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 memoria update use HTTPS_PROXY and the system certificates. For uv, also set UV_SYSTEM_CERTS=1.

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

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/).