DEV Community: Carloshperc

AI agent memory you verify, not just trust

Carloshperc — Fri, 03 Jul 2026 18:34:48 +0000

TL;DR

A CLAUDE.md solves static knowledge: commands, conventions, preferences and rules. What it does not solve is episodic memory: yesterday's investigated bug, the approach that already failed, the decision that explains why a PR was abandoned. That is why I built agent-memory-hub. The turn came later: I discovered the memory itself could fail silently. This article is the story of how persistent memory became verifiable memory, and how a product idea became an open-source tool I actually use every day.

Who this article is for

Devs using Claude Code, Codex or Cursor who feel the agent knows the rules but forgets the story.
Anyone maintaining CLAUDE.md, AGENTS.md or persistent memory who wants to separate static knowledge from episodic memory.
Anyone who enjoys an honest post-mortem: a silent pipeline bug, observability and a deliberate product call.

The whole story in one line

If I told this in the most obvious way, the summary would be: I built a memory, found bugs, added observability. But that summary starts in the wrong place. The story did not become interesting because a bug appeared. It became interesting because the bug showed I was trusting a memory without a receipt.

That order changes the weight of everything. agent-memory-hub started as a continuity layer for coding agents. Then it became a practical lesson about ingestion: anything that captures data automatically also needs to prove that it captured it. Without that, memory only looks like memory.

The pain wasn't intelligence. It was memory.

Over the last few months I practically stopped coding without AI agents. Claude Code, Codex, Cursor: when you give them enough context, each tool gets very good at entering a project and producing.

So I did what almost everyone does: I wrote a good CLAUDE.md. I put in build commands, conventions, how I like tests written, how I organize modules, how I open PRs. It worked very well, until I noticed a curious split: the agent knew how I wanted it to work, but it did not remember what had already happened.

It knew how to compile. But it did not remember that yesterday we had already tried another approach. It knew how to run tests. But it forgot that a bug had already been investigated for two hours. It knew the rules. But it did not know the story.

The habit that masked the problem

For a while I compensated in the most human way possible: by repeating myself. I would open a new session and dump context. "Yesterday we tried this." "Do not touch that layer because it has odd coupling." "This test fails when it runs in parallel." "The previous PR decision was to take another path."

The curious thing is that this repetition felt like a natural part of using agents. Since the answer improved after I explained everything again, I did not see it as a system failure. It felt like an entry ritual: before working, recap. The problem is that manual ritual charges interest when you move across projects, machines and tools.

That was the first important insight: the agent did not only need better instructions. It needed continuity. And continuity is not a long prompt. It is the ability to carry consequences from one session to the next.

There are two kinds of knowledge

Once I separated the problem, it became clear that I was calling two different things "context". One is static: how to compile, how to deploy, how to structure a module, how to write commits.

That knowledge belongs in CLAUDE.md. The other part changes every day: yesterday's investigated bug, the decision made in the last session, the experiment that failed, the reason a PR was abandoned. That does not belong in CLAUDE.md, because the file would need to be rewritten constantly. It is memory. Episodic, living, automatic.

CLAUDE.md / AGENTS.md	agent-memory-hub
How to work	What already happened
Static	Dynamic
Written by you	Captured automatically
Rules	History

That is where agent-memory-hub was born. Not to replace CLAUDE.md, but to solve exactly what it was never meant to solve.

What I wanted the memory to remember

When you use agents occasionally, repeating context feels like an annoyance. When they enter the daily workflow, it becomes operational cost. The problem was not storing "preferences"; it was preserving continuity between sessions that, to the tool, looked independent.

In practice, I wanted memory to keep five kinds of episodes: decisions made, hypotheses discarded, bugs already investigated, PR state of mind and small project patterns that only show up after several conversations.

That boundary protected the project from becoming a dump of everything. If everything is memory, nothing is memory. The value was in capturing what I would actually forget between sessions, especially when I moved across machines, tools and contexts.

From there, the question stopped being "which memory tool exists?" and became something else: what kind of system could capture those episodes without trapping my history inside a single tool?

Why I built it myself

I could have stopped there and adopted an existing tool. There are good options for agent memory, and I was not trying to reinvent vector search for sport. But my problem had very personal requirements: work across Claude Code and Codex, cross machines, remain mine when I changed tools, and be auditable with a simple SQL query.

Choosing Postgres via Supabase was less about technical glamour and more about predictability. I wanted data ownership, pg_dump, direct inspection, a table I could open without asking any product for permission. For personal work memory, that matters. My session history is part of my process, not just a tool cache.

That decision raised the stakes for what came next. When you buy a tool, you accept part of the black box as the package. When you build the pipeline, responsibility moves: if it fails silently, it is not the fault of some distant platform. It is the architecture you chose to tolerate.

The first version looked perfect

The architecture was simple: every session was captured automatically and, at the start of the next conversation, the agent received a digest of relevant sessions. Underneath it, hybrid search (keyword + pgvector) and an optional facts layer. Everything was saved to my own Postgres (via Supabase), with no SaaS, no lock-in, and the ability to run pg_dump at any time.

The design: three lifecycle hooks write to and read from the same Postgres table. Capture is idempotent (upsert by session_id); the Stop checkpoint keeps the session alive even through an abrupt kill.

It worked across machines. It worked across tools. It worked so well that I stopped thinking about it. That was the danger: the automation had disappeared from my attention.

You stop verifying because the system looks reliable, and the system looks reliable precisely because failures do not surface. Until the day I decided to check one specific session.

The day of the ghost session

The session that made me pull this thread did not look special. It was just another long conversation, the kind where you stack context, small decisions, command output and course corrections. At some point, a simple question landed: "did this get saved?".

The question was almost bureaucratic. I was not hunting for a bug. I only wanted to confirm that memory had done its job. I checked the log. Nothing. I checked the database. Nothing. The session that had just happened did not exist for the system that was supposed to remember it.

That kind of moment changes your relationship with a tool. Until then, I thought of memory as convenience. After that, I started seeing it as infrastructure. And infrastructure that fails without signaling is not infrastructure; it is a silent bet.

The error was hidden in `exit 0`

When I followed the trace, the pattern became more uncomfortable than one missing session. There were intermittent errors: session yes, session no. Some conversations reached the database; others disappeared on the way.

The capture hook had an except that swallowed any error and moved on with exit 0. From Claude Code's point of view, all good. From the database's point of view, whole sessions were missing.

And that's worse than a crash. A crash you see: it stops, it screams, it shows up. Silence you don't see. The agent simply "forgets" things it should know, and you chalk it up to a model limitation, not a broken pipeline. The memory looked like it worked because nobody had to prove that it worked.

Why silent failure is so deceptive

Silent failure does not compete with your system. It competes with your interpretation of the system. When the agent forgets something, plausible explanations remain: the model did not weigh it enough, the summary was weak, the initial prompt did not include context, semantic search did not find the right session.

All of those explanations can be true. That is exactly why they are dangerous. They give you a comfortable story for a problem that may sit one step earlier: the information was never captured. You keep tuning recall, embeddings and prompts while the hole is in ingestion.

That is when the word "trust" started to feel wrong. Trust, in that context, was just the absence of evidence against. What I needed was evidence for.

The investigation: follow the data, not intuition

The initial temptation was to fix the first visible error and declare victory. But ingestion pipelines rarely break in only one place. The data crossed shell, Python parser, sanitization, Postgres insert and logs. Any one of those layers could be lying by omission.

So I followed the payload like a trail: was the original input valid? Did it arrive unchanged in Python? Did the parser accept it? Did the database reject it? Did the log record the failure? Did the hook return an error to the tool?

That changed the tone of the investigation. The bug stopped being "why did one session disappear?" and became "how many sessions could disappear without me noticing?". The second question is much more uncomfortable, and much more useful.

Three bugs, all silent

What looked like one problem turned into three, at different layers of the same pipeline. The detail is worth it because this pattern shows up in any ingestion system that seems too "simple" to fail.

Bug 1: control characters

Each session payload is JSON. Python's strict parser rejected any payload with unescaped control characters, and the content of a terminal session is full of them (command output, box-drawing, ANSI sequences). The result was a JSONDecodeError the except swallowed.

The fix is one line, but it only works because the error was in the parse:

payload = json.load(sys.stdin, strict=False)  # accept control chars inside strings

Bug 2: the NUL byte

With a tolerant parser, another session failed, now at the database. Postgres refuses the NUL byte in a text column, with the error 22P05: unsupported Unicode escape sequence. So: the parse passed, but the INSERT was rejected. The fix was to sanitize the content, recursively, before uploading:

def strip_nul(obj):
    if isinstance(obj, str):
        return obj.replace("\x00", "")
    if isinstance(obj, dict):
        return {k: strip_nul(v) for k, v in obj.items()}
    if isinstance(obj, list):
        return [strip_nul(v) for v in obj]
    return obj

Bug 3: the `echo` that corrupted the JSON

This one was the subtlest, and the most instructive. The hook command captured the payload and handed it to Python like this:

payload=$(cat); echo "$payload" | python3 capture_session.py ...

The problem is echo. In sh/dash, echo interprets backslash sequences. Any payload with \ (and sessions have many: ANSI sequences, regex, \u) reached the parser corrupted, with the error Invalid \escape. That's why it alternated: a session with a backslash failed, a session without one passed. The parser never had a chance; the data arrived already broken.

The fix is to swap echo for printf '%s', which doesn't interpret escapes. The side-by-side test proves the point, with the same valid JSON input:

# same valid input; via echo it breaks, via printf it passes
sh -c 'p=$(cat in.json); echo "$p"'        | python3 -c 'import json,sys; json.load(sys.stdin)'
# -> JSONDecodeError: Invalid \escape

sh -c 'p=$(cat in.json); printf "%s" "$p"' | python3 -c 'import json,sys; json.load(sys.stdin)'
# -> ok

The cross-cutting lesson: every layer (parser, database, shell) had a different trap for the same data. A "simple" three-stage pipeline hid three independent failure modes, all silent.

Fixing the present was not enough

After fixing the hook, one annoying question remained: what about the past? The sessions that failed would not magically return just because the new code was better. If memory is history, old gaps matter too. Sometimes they matter more, because that is where the decisions and attempts I did not want to repeat were stored.

Backfill became part of the fix. I had to reconcile local transcripts, identify sessions that existed on the filesystem but not in the database, sanitize old payloads, attach subagent sessions and deal with a second account that also had relevant history. It was not glamorous. It was infrastructure cleanup.

flowchart LR
  L["Local transcripts"] --> C["Classify valid sessions"]
  C --> M["Find missing in DB"]
  M --> S["Sanitize old payload"]
  S --> U["Idempotent upsert"]
  U --> H["health confirms coverage"]
  H --> R["History whole again"]

That detail is easy to underestimate. Many pipeline fixes stop at "from now on it is fine". But for memory, the past is the product. If you only fix the future, you leave the most valuable part of the tool with invisible gaps.

The pivot: the problem isn't remembering, it's verifying

Fixing the bugs was the easy part. What stuck was the question they forced: I spent weeks trusting something broken and never knew. The problem was not only technical. It was epistemological: why did I think that memory deserved trust?

Because the metric the whole category optimizes is "remember better": smarter recall, better embeddings, denser summaries. That matters. But the pain that caught me was one step earlier: proof that capture happened. Nobody tells you when memory fails. There's no receipt, no health check, no gap detection. You find out when the agent forgets, if you find out.

So I stopped treating trust as a feeling and started building verification. Two pieces:

A coverage health check. A command that reconciles local transcripts (from every tool) against what's in the database, ignores empty sessions, and watches the capture error rate over the last 24 hours. The output is direct:

agent-memory-hub · health

✓ coverage    ██████████████████████ 86/86 local sessions saved
✓ capture     last 24h: 51 ok, 0 errors
✓ subagents   13/13 sessions with subagents attached

flowchart LR
  L["Local transcripts<br/>(all tools)"] --> R{"health: reconcile"}
  B[("DB · public.sessions")] --> R
  R -->|"gap or capture error"| ALERT["surfaced: coverage under 100%"]
  R -->|"all matched"| OKN["86/86 · 0 errors / 24h"]

When something breaks, it surfaces, instead of going unnoticed. It's the difference between memory you trust and memory you verify.

An MCP server for on-demand recall. The default recall is passive: it injects a digest at the start of the session, before you even say what you want to do. I exposed the memory as MCP tools (pure stdlib, no dependencies) so the agent queries the memory with the task in hand: recall_relevant, recent_sessions, get_facts, get_session. The idea was simple: remember at the right time, not only at the beginning of the conversation. The heart of the server is a minimal JSON-RPC handler:

elif method == "tools/call":
    text = _call(params["name"], params.get("arguments") or {})
    _reply(rid, {"content": [{"type": "text", "text": text}]})

The numbers, after closing everything: 148 sessions, 36 projects, local↔database coverage reconciled, with a second account's sessions and subagent transcripts finally included in the backfill.

The system changed personality

Before, memory was an optimistic promise: "relax, I saved it". Afterward, it became a system with a more mature posture: "I saved these sessions, I did not save those, and here is the difference between what exists locally and what reached the database".

That also changed how I use agents. When recall feels poor, there is now a question before model quality: was the memory available? Was the relevant session captured? Did the agent query the right history? Without that layer, every failure looks like "the AI's fault". With it, forgetting becomes something you can investigate.

What the project does today

After that sequence of fixes, agent-memory-hub stopped being just a pair of hooks. It became a small personal memory platform for agents: capture, query, verification, console, adapters, backup, profile and quality evaluation. It did not start that way; it became that every time a failure asked for a better surface.

Layer	What it solves today
Capture	Claude Code hooks save sessions; adapters pull history from Codex and Cursor.
Query	Session-start recall, on-demand MCP and the `mem` console to search, inspect and summarize.
Observability	`health` reconciles local transcripts with the database; `log` shows what happened.
Quality	Pytest suite, CI and a recall evaluation harness with hit@k/MRR.
Evolution	The cross-project profile proposes rules; you approve before they become behavior.

The commits tell that evolution well. First came the capture bugs. Then health and log. Then MCP, standup, adapters for other tools, packaging for the mem command, CI tests and recall evaluation. Even ranking tuning entered the loop: a recency bias was tested and rejected by data when it hurt recall.

That changes the reading of the project. It is not an idea abandoned after market research. It is a living, used tool, with commits stacking real learning. The care was different: not confusing open-source traction and daily usefulness with an obligation to turn everything into a company immediately.

Before turning it into a startup, I stress-tested the thesis

The seductive version of the story would stop here and say: I found a real pain, built a solution, now there is an opportunity. And for a few hours, I wanted to believe that. "Verifiable memory for agents" sounds like a category. It seems to have a name, urgency and a clear angle.

But a real pain is not automatically a company. So I changed the question. Instead of looking for confirmation, I looked for friction: who is already close to this? What can incumbents copy quickly? What is deep pain and what is an adjacent feature? If I were my own competitor, how long would it take to neutralize this slice?

That research did not reduce the value of the project. On the contrary: it made the value clearer. As a personal tool, it saves me time and reduces repetition every day. As an open-source project, it has already started getting stars and signaling that the pain resonates outside my own machine. As a startup, it might still need a broader thesis than "proof of capture". And that is fine. Not every useful project needs to become a company before it finishes learning its own shape.

What worked: daily use and real signals

The part I am proudest of is that the project did not stay in idea-land. It is in my daily workflow. It captures sessions, shows up at the start of new conversations, helps recover old decisions and reduces the annoying work of re-explaining context to the agent.

It also did not stay invisible to other people. The repo has already received stars, and that matters as a small but honest signal: not market validation, but proof that the pain is recognizable. The adversarial research was not there to abandon the project; it was there to calibrate ambition. The result was sober:

Tool	What it already covers	The gap that still remains
MemGuard	"Datadog for agent memory": health and trust-scoring.	Proof of capture, silent-gap detection, "memory receipts". Real, but thin, and copyable by incumbents in weeks.
Zep	Enterprise governance: SOC 2 Type II, HIPAA, access audit.
MemTrust (paper, 2026)	Crypto-chained audit and memory attestation.
mem0	An audit Events API already built in.

The "observe/trust the memory" theme is filling up fast. The exact slice still open (proof of capture, silent-gap detection, "memory receipts") is real, but it's thin, and copyable by incumbents in weeks (mem0, for instance, already has an audit Events API).

So the decision was to keep using it, keep opening it, keep improving it and not force a startup narrative before its time. Today the value is clear: real dogfood, open-source, public signs of interest, and useful enough to stay in my daily workflow.

One honest technical caveat, for anyone replicating: the hook fix only applies to new sessions, because hooks load at the start of the session. The safety net is the session-end event, which saves the whole transcript cleanly, so even with the intermediate checkpoints failing, the final state isn't lost.

Conclusion

If you run agents with memory, do one thing this week: check that it's actually capturing. Don't assume. Look for the equivalent of my "checked the log, checked the database". The most dangerous failure mode of an ingestion pipeline isn't the one that screams, it's the one that fails quietly and leaves you confident.

The principle generalizes beyond AI agents: for any system that ingests data and can fail silently, observability beats optimization. Verifying is more important than trusting. And the product meta-lesson, maybe the most useful: running adversarial research to calibrate your own ambition is a superpower, not a defeat. Sometimes the best outcome of an investigation is understanding that the project should stay alive, just in the right shape.

The project is open-source and self-hosted. If it saves you a single session re-explaining your project to the agent, it was worth it.

Originally published at buildcomcarlos.com.

Memória de agente de IA que você verifica, não só confia

Carloshperc — Fri, 03 Jul 2026 18:30:56 +0000

TL;DR

Um CLAUDE.md resolve conhecimento estático: comandos, convenções, preferências e regras. O que ele não resolve é memória episódica: o bug investigado ontem, a abordagem que já falhou, a decisão que explica por que um PR foi abandonado. Foi para isso que construí o agent-memory-hub. A virada veio depois: eu descobri que a própria memória podia falhar em silêncio. Este artigo é a história de como uma memória persistente virou memória verificável, e de como uma ideia de produto virou uma ferramenta open-source que eu uso de verdade no dia a dia.

Para quem é este artigo

Devs que usam Claude Code, Codex ou Cursor e sentem que o agente sabe as regras, mas esquece a história.
Quem mantém CLAUDE.md, AGENTS.md ou memória persistente e quer separar conhecimento estático de memória episódica.
Quem gosta de pós-morte honesto: bug silencioso de pipeline, observabilidade e uma decisão de produto deliberada.

A história inteira em uma linha

Se eu contasse isso do jeito mais óbvio, o resumo seria: construí uma memória, encontrei bugs, adicionei observabilidade. Só que esse resumo começa pelo lugar errado. A história não ficou interessante porque um bug apareceu. Ficou interessante porque o bug mostrou que eu estava confiando em uma memória sem recibo.

Essa ordem muda o peso de tudo. O agent-memory-hub começou como uma solução de continuidade para agentes de código. Depois virou uma aula prática de ingestão: qualquer coisa que captura dados automaticamente também precisa provar que capturou. Sem isso, a memória só parece memória.

A dor não era inteligência. Era memória.

Nos últimos meses eu praticamente parei de programar sem agentes de IA. Claude Code, Codex, Cursor: quando você dá contexto suficiente, cada ferramenta fica muito boa em entrar no projeto e produzir.

Então fiz o que quase todo mundo faz: escrevi um bom CLAUDE.md. Coloquei comandos de build, convenções, como gosto de escrever testes, como organizo módulos, como abro PRs. Funcionava muito bem, até eu perceber uma divisão curiosa: o agente sabia como eu queria que ele trabalhasse, mas não lembrava o que já tinha acontecido.

Sabia compilar. Mas não lembrava que ontem já tínhamos tentado outra abordagem. Sabia rodar os testes. Mas esquecia que aquele bug já tinha sido investigado durante duas horas. Sabia as regras. Mas não conhecia a história.

O hábito que mascarava o problema

Por um tempo eu compensei isso do jeito mais humano possível: repetindo. Abria uma sessão nova e despejava contexto. "Ontem tentamos isso." "Não mexe nessa camada porque ela tem um acoplamento estranho." "Esse teste falha quando roda em paralelo." "A decisão do PR anterior foi seguir por outro caminho."

O curioso é que essa repetição parecia parte natural do uso de agentes. Como a resposta melhorava depois que eu explicava tudo de novo, eu não enxergava aquilo como falha de sistema. Parecia só o ritual de entrada: antes de trabalhar, recapitular. O problema é que ritual manual cobra juros quando você alterna entre projetos, máquinas e ferramentas.

Esse foi o primeiro insight importante: o agente não precisava apenas de instruções melhores. Ele precisava de continuidade. E continuidade não é prompt longo. É a capacidade de carregar consequência de uma sessão para outra.

Existem dois tipos de conhecimento

Quando comecei a separar o problema, ficou claro que eu estava chamando duas coisas diferentes de "contexto". Uma é estática: como compilar, como fazer deploy, como estruturar um módulo, como escrever commits.

Esse conhecimento pertence ao CLAUDE.md. A outra parte muda todo dia: o bug investigado ontem, a decisão da última sessão, o experimento que deu errado, o motivo de um PR ter sido abandonado. Isso não pertence ao CLAUDE.md, porque ele teria que ser reescrito o tempo inteiro. É memória. Episódica, viva, automática.

CLAUDE.md / AGENTS.md	agent-memory-hub
Como trabalhar	O que já aconteceu
Estático	Dinâmico
Escrito por você	Capturado automaticamente
Regras	História

Foi aí que nasceu o agent-memory-hub. Não para substituir o CLAUDE.md, mas para resolver justamente aquilo que ele nunca foi feito para resolver.

O que eu queria que a memória lembrasse

Quando você usa agentes de vez em quando, repetir contexto parece só um incômodo. Quando eles entram no fluxo diário, vira custo operacional. O problema não era guardar "preferências"; era preservar continuidade entre sessões que, para a ferramenta, pareciam independentes.

Na prática, eu queria que a memória guardasse cinco tipos de episódio: decisões tomadas, hipóteses descartadas, bugs já investigados, estado mental de PRs e pequenos padrões de projeto que só aparecem depois de várias conversas.

Esse recorte protegia o projeto de virar um "depósito de tudo". Se tudo é memória, nada é memória. O valor estava em capturar aquilo que eu realmente esqueceria entre uma sessão e outra, especialmente quando alternava entre máquinas, ferramentas e contextos.

A partir daí, a pergunta deixou de ser "qual ferramenta de memória existe?" e virou outra: que tipo de sistema conseguiria capturar esses episódios sem prender meu histórico em uma ferramenta só?

Por que construir em casa

Eu poderia ter parado aqui e adotado uma ferramenta pronta. Existem boas opções para memória de agente, e eu não queria reinventar busca vetorial por esporte. Mas meu problema tinha exigências muito pessoais: funcionar entre Claude Code e Codex, atravessar máquinas, continuar meu quando eu trocasse de ferramenta e ser auditável com uma consulta SQL simples.

A escolha por Postgres via Supabase veio menos por glamour técnico e mais por previsibilidade. Eu queria posse dos dados, pg_dump, inspeção direta, uma tabela que eu pudesse abrir sem pedir licença para produto nenhum. Para memória pessoal de trabalho, isso pesa. O histórico das minhas sessões é parte do meu processo, não só cache de uma ferramenta.

Essa decisão aumentou o peso do que viria depois. Quando você compra uma ferramenta, aceita parte da caixa-preta como pacote. Quando constrói o pipeline, a responsabilidade muda de lugar: se ele falha em silêncio, a culpa não é de uma plataforma distante. É da arquitetura que você escolheu tolerar.

A primeira versão parecia perfeita

A arquitetura era simples: cada sessão era capturada automaticamente e, no início da próxima conversa, o agente recebia um resumo das sessões relevantes. Por baixo, busca híbrida (palavra-chave + pgvector) e uma camada opcional de fatos. Tudo salvo no meu próprio Postgres (via Supabase), sem SaaS, sem lock-in, com a capacidade de rodar pg_dump a qualquer momento.

O desenho: três hooks de ciclo de vida escrevem e leem a mesma tabela Postgres. Captura idempotente (upsert por session_id); o checkpoint do Stop preserva a sessão até um kill abrupto.

Funcionava entre máquinas. Funcionava entre ferramentas. Funcionava tão bem que eu parei de pensar nela. Esse foi o perigo: a automação tinha sumido da minha atenção.

Você deixa de verificar porque o sistema parece confiável, e o sistema parece confiável justamente porque as falhas não aparecem na superfície. Até o dia em que eu resolvi conferir uma sessão específica.

O dia da sessão fantasma

A sessão que me fez puxar esse fio não parecia especial. Era só mais uma conversa longa, dessas em que você empilha contexto, decisões pequenas, saídas de comando e ajustes de rota. Em algum momento, bateu uma dúvida simples: "será que isso foi salvo?".

A pergunta era quase burocrática. Eu não estava caçando bug. Só queria confirmar que a memória tinha feito o trabalho dela. Fui no log. Nada. Fui no banco. Nada. A sessão que tinha acabado de acontecer não existia para o sistema que deveria lembrar dela.

Esse tipo de momento muda sua relação com uma ferramenta. Até ali, eu pensava na memória como comodidade. Depois disso, passei a enxergar como infraestrutura. E infraestrutura que falha sem sinalização não é infraestrutura: é uma aposta silenciosa.

O erro estava escondido no `exit 0`

Quando segui o rastro, o padrão ficou mais desconfortável do que uma sessão perdida. Havia erros intermitentes: sessão sim, sessão não. Algumas conversas chegavam ao banco; outras desapareciam no caminho.

O hook de captura tinha um except que engolia qualquer erro e seguia em frente com exit 0. Do ponto de vista do Claude Code, tudo certo. Do ponto de vista do banco, faltavam sessões inteiras.

E isso é pior do que um crash. Crash você vê: ele para, grita, aparece. Silêncio você não vê. O agente simplesmente "esquece" coisas que deveria saber, e você atribui isso a uma limitação do modelo, não a um pipeline quebrado. A memória parecia funcionar porque ninguém era obrigado a provar que ela tinha funcionado.

Por que falha silenciosa é tão traiçoeira

A falha silenciosa não compete com o seu sistema. Ela compete com a sua interpretação do sistema. Quando o agente esquece algo, sobram explicações plausíveis: o modelo não deu peso suficiente, o resumo ficou ruim, o prompt inicial não trouxe contexto, a busca semântica não encontrou a sessão certa.

Todas essas explicações podem ser verdadeiras. E justamente por isso são perigosas. Elas dão uma narrativa confortável para um problema que talvez esteja um passo antes: a informação nunca foi capturada. Você fica ajustando recall, embeddings e prompt, enquanto o buraco está na ingestão.

Foi aí que a palavra "confiança" começou a parecer errada. Confiança, naquele contexto, era só ausência de evidência contra. O que eu precisava era evidência a favor.

A investigação: seguir o dado, não a intuição

A tentação inicial era corrigir o primeiro erro visível e declarar vitória. Mas pipeline de ingestão raramente quebra em um lugar só. O dado atravessava shell, parser Python, sanitização, insert no Postgres e logs. Qualquer uma dessas camadas podia estar mentindo por omissão.

Então eu fui seguindo o payload como quem segue uma trilha: a entrada original era válida? Ela chegava igual ao Python? O parser aceitava? O banco recusava? O log registrava a falha? O hook devolvia erro para a ferramenta?

Foi isso que mudou o tom da investigação. O bug deixou de ser "por que uma sessão sumiu?" e virou "quantas sessões poderiam sumir sem eu perceber?". Essa segunda pergunta é muito mais desconfortável, e muito mais útil.

Três bugs, todos silenciosos

O que parecia um problema virou três, em camadas diferentes do mesmo pipeline. Vale entrar no detalhe porque esse padrão aparece em qualquer sistema de ingestão que parece "simples" demais para falhar.

Bug 1: caracteres de controle

O payload de cada sessão é JSON. O parser estrito do Python rejeitava qualquer payload com caracteres de controle não-escapados, e o conteúdo de uma sessão de terminal está cheio deles (output de comandos, box-drawing, sequências ANSI). O resultado era um JSONDecodeError que o except engolia.

A correção é de uma linha, mas só funciona porque o erro estava no parse:

payload = json.load(sys.stdin, strict=False)  # aceita control chars dentro das strings

Bug 2: o byte nulo

Com o parser tolerante, outra sessão falhou, agora no banco. O Postgres recusa o byte nulo em coluna text, com o erro 22P05: unsupported Unicode escape sequence. Ou seja: o parse passava, mas o INSERT era rejeitado. A correção foi sanitizar o conteúdo, recursivamente, antes de subir:

def strip_nul(obj):
    if isinstance(obj, str):
        return obj.replace("\x00", "")
    if isinstance(obj, dict):
        return {k: strip_nul(v) for k, v in obj.items()}
    if isinstance(obj, list):
        return [strip_nul(v) for v in obj]
    return obj

Bug 3: o `echo` que corrompia o JSON

Este foi o mais sutil, e o mais instrutivo. O comando do hook capturava o payload e o repassava ao Python assim:

payload=$(cat); echo "$payload" | python3 capture_session.py ...

O problema é o echo. Em sh/dash, echo interpreta sequências de barra invertida. Qualquer payload com \ (e sessões têm muitos: sequências ANSI, regex, \u) chegava corrompido ao parser, com o erro Invalid \escape. Por isso alternava: sessão com barra invertida falhava, sessão sem barra passava. O parser nunca teve chance; o dado já chegava quebrado.

A correção é trocar echo por printf '%s', que não interpreta escapes. O teste lado a lado prova o ponto, com a mesma entrada JSON válida:

# mesma entrada válida; via echo quebra, via printf passa
sh -c 'p=$(cat in.json); echo "$p"'        | python3 -c 'import json,sys; json.load(sys.stdin)'
# -> JSONDecodeError: Invalid \escape

sh -c 'p=$(cat in.json); printf "%s" "$p"' | python3 -c 'import json,sys; json.load(sys.stdin)'
# -> ok

A lição transversal: cada camada (parser, banco, shell) tinha uma armadilha diferente para o mesmo dado. Um pipeline "simples" de três etapas escondia três modos de falha independentes, todos silenciosos.

Consertar o presente não bastava

Depois de corrigir o hook, ainda sobrava uma pergunta chata: e o passado? As sessões que falharam não voltariam magicamente só porque o código novo estava melhor. Se a memória é história, buraco antigo também importa. Às vezes importa mais, porque ali estavam decisões e tentativas que eu não queria repetir.

O backfill virou parte da correção. Eu precisei reconciliar transcripts locais, identificar sessões que existiam no filesystem mas não no banco, sanitizar payloads antigos, anexar sessões de subagentes e lidar com uma segunda conta que também tinha histórico relevante. Não era glamouroso. Era faxina de infraestrutura.

flowchart LR
  L["Transcripts locais"] --> C["Classificar sessões válidas"]
  C --> M["Encontrar ausentes no banco"]
  M --> S["Sanitizar payload antigo"]
  S --> U["Upsert idempotente"]
  U --> H["health confirma cobertura"]
  H --> R["História volta a ficar inteira"]

Esse detalhe é fácil de subestimar. Muita correção de pipeline para no "daqui para frente está bom". Só que, para memória, o passado é o produto. Se você corrige apenas o futuro, deixa a parte mais valiosa da ferramenta com lacunas invisíveis.

A virada: o problema não é lembrar, é verificar

Consertar os bugs foi o de menos. O que ficou foi a pergunta que eles forçaram: eu passei semanas confiando numa coisa quebrada e não soube. O problema não era só técnico. Era epistemológico: por que eu achava que aquela memória merecia confiança?

Porque a métrica que a categoria inteira otimiza é "lembrar melhor": recall mais esperto, embeddings melhores, resumos mais densos. Isso importa. Mas a dor que me pegou estava um passo antes: prova de que a captura aconteceu. Ninguém te avisa quando a memória falha. Não há recibo, não há health check, não há detecção de gap. Você descobre quando o agente esquece, se descobrir.

Então parei de tratar confiança como sentimento e passei a construir verificação. Duas peças:

Um health check de cobertura. Um comando que reconcilia os transcripts locais (de todas as ferramentas) contra o que está no banco, ignora sessões vazias, e vigia a taxa de erro da captura nas últimas 24 horas. A saída é direta:

agent-memory-hub · health

✓ cobertura   ██████████████████████ 86/86 sessões locais salvas
✓ captura     últimas 24h: 51 ok, 0 erros
✓ subagentes  13/13 sessões com subagentes anexados

flowchart LR
  L["Transcripts locais<br/>(todas as ferramentas)"] --> R{"health: reconcilia"}
  B[("DB · public.sessions")] --> R
  R -->|"gap ou erro de captura"| ALERT["aparece: cobertura abaixo de 100%"]
  R -->|"tudo bateu"| OKN["86/86 · 0 erros / 24h"]

Quando algo quebra, isso aparece, em vez de passar batido. É a diferença entre memória que você confia e memória que você verifica.

Um servidor MCP para recall sob demanda. O recall padrão é passivo: injeta um resumo no início da sessão, antes de você sequer dizer o que quer fazer. Expus a memória como ferramentas MCP (em stdlib puro, sem dependências) para que o agente consulte a memória com o contexto da tarefa em mãos: recall_relevant, recent_sessions, get_facts, get_session. A ideia era simples: lembrar na hora certa, não só no começo da conversa. O coração do servidor é um handler JSON-RPC minimalista:

elif method == "tools/call":
    text = _call(params["name"], params.get("arguments") or {})
    _reply(rid, {"content": [{"type": "text", "text": text}]})

Os números, depois de fechar tudo: 148 sessões, 36 projetos, cobertura local↔banco reconciliada, com as sessões de uma segunda conta e os transcripts de subagentes finalmente incluídos no backfill.

O sistema mudou de personalidade

Antes, a memória era uma promessa otimista: "fica tranquilo, eu salvei". Depois, ela virou um sistema com postura mais adulta: "eu salvei estas sessões, não salvei aquelas, e aqui está a diferença entre o que existe localmente e o que chegou ao banco".

Isso também mudou como eu uso agentes. Quando o recall parece ruim, agora existe uma pergunta anterior à qualidade do modelo: a memória estava disponível? A sessão relevante foi capturada? O agente consultou a história certa? Sem essa camada, qualquer falha parece "culpa da IA". Com ela, o esquecimento vira algo que dá para investigar.

O que o projeto faz hoje

Depois dessa sequência de correções, o agent-memory-hub deixou de ser só um par de hooks. Virou uma pequena plataforma pessoal de memória para agentes: captura, consulta, verificação, console, adapters, backup, perfil e avaliação de qualidade. Não nasceu assim; foi ficando assim cada vez que uma falha pedia uma superfície melhor.

Camada	O que resolve hoje
Captura	Hooks do Claude Code salvam sessões; adapters puxam histórico de Codex e Cursor.
Consulta	Recall no início da sessão, MCP sob demanda e console `mem` para buscar, inspecionar e resumir.
Observabilidade	`health` reconcilia transcripts locais com o banco; `log` mostra o que aconteceu.
Qualidade	Suite pytest, CI e harness de avaliação de recall com hit@k/MRR.
Evolução	Perfil cross-projeto propõe regras; você aprova antes de virar comportamento.

Os commits contam bem essa evolução. Primeiro vieram os bugs de captura. Depois health e log. Em seguida MCP, standup, adapters para outras ferramentas, empacotamento do comando mem, testes em CI e avaliação de recall. Até tuning de ranking entrou no fluxo: a ideia de aplicar viés de recência foi testada e rejeitada por dados quando piorou o recall.

Isso muda a leitura do projeto. Ele não é uma ideia abandonada depois de uma pesquisa de mercado. É uma ferramenta viva, usada, com commits empilhando aprendizado real. O cuidado foi outro: não confundir tração open-source e utilidade diária com a obrigação de transformar tudo em empresa imediatamente.

Antes de virar startup, eu testei a tese

A parte sedutora da história seria parar aqui e dizer: encontrei uma dor real, construí uma solução, agora existe uma oportunidade. E, por algumas horas, eu quis acreditar nisso. "Memória verificável para agentes" soa como categoria. Parece ter nome, urgência e um ângulo claro.

Mas uma dor real não é automaticamente uma empresa. Então eu mudei a pergunta. Em vez de procurar confirmação, procurei atrito: quem já está perto disso? O que incumbentes conseguem copiar rápido? O que é dor profunda e o que é feature adjacente? Se eu fosse concorrente de mim mesmo, quanto tempo levaria para neutralizar esse recorte?

Essa pesquisa não diminuiu o valor do projeto. Pelo contrário: deixou o valor mais claro. Como ferramenta pessoal, ele me economiza tempo e reduz repetição todo dia. Como projeto open-source, já começou a receber stars e sinalizar que a dor ressoa fora da minha máquina. Como startup, talvez ainda precisasse de uma tese mais larga do que "prova de captura". E tudo bem. Nem todo projeto útil precisa virar empresa antes de terminar de aprender o próprio formato.

O que funcionou: uso diário e sinais reais

A parte que mais me orgulho é que o projeto não ficou no campo da ideia. Ele está no meu fluxo diário. Captura sessões, aparece no começo de conversas novas, ajuda a recuperar decisões antigas e reduz aquele trabalho chato de reexplicar contexto para o agente.

Também não ficou invisível para outras pessoas. O repo já recebeu stars, e isso importa como sinal pequeno, mas honesto: não é validação de mercado, mas mostra que a dor é reconhecível. A pesquisa adversarial não serviu para abandonar o projeto; serviu para calibrar a ambição. O resultado foi sóbrio:

Ferramenta	O que já cobre	O recorte que ainda sobra
MemGuard	"Datadog para memória de agente": health e trust-scoring.	Prova de captura, detecção de gap silencioso, "recibos de memória". Real, mas fino, e copiável pelos incumbentes em semanas.
Zep	Governança enterprise: SOC 2 Type II, HIPAA, audit de acesso.
MemTrust (paper, 2026)	Audit cripto-encadeado e attestation da memória.
mem0	Events API de auditoria já embutida.

O tema "observar/confiar na memória" está enchendo rápido. O recorte exato que sobra aberto (prova de captura, detecção de gap silencioso, "recibos de memória") é real, mas é fino, e copiável pelos incumbentes em semanas (o mem0, por exemplo, já tem um Events API de auditoria).

Então a decisão foi continuar usando, continuar abrindo, continuar melhorando e não forçar uma narrativa de startup antes da hora. Hoje o valor está bem claro: é dogfood real, open-source, com sinais públicos de interesse, e útil o suficiente para permanecer no meu dia a dia.

Um limite técnico honesto, para quem for replicar: a correção do hook só vale em sessões novas, porque hooks são carregados no início da sessão. A rede de segurança é o evento de fim de sessão, que salva o transcript inteiro de forma limpa, então mesmo com os checkpoints intermediários falhando, o estado final não se perde.

Conclusão

Se você roda agentes com memória, faça uma coisa esta semana: cheque se ela está capturando de verdade. Não assuma. Procure o equivalente do meu "fui no log, fui no banco". O modo de falha mais perigoso de um pipeline de ingestão não é o que grita, é o que falha calado e te deixa confiante.

O princípio generaliza para além de agentes de IA: para qualquer sistema que ingere dados e pode falhar em silêncio, observabilidade vale mais que otimização. Verificar é mais importante do que confiar. E o meta-aprendizado de produto, talvez o mais útil: rodar pesquisa adversarial para calibrar a própria ambição é um superpoder, não uma derrota. Às vezes o melhor resultado de uma investigação é entender que o projeto deve continuar vivo, só que no formato certo.

O projeto é open-source e self-hosted. Se te economizar uma única sessão re-explicando seu projeto ao agente, já valeu.

Publicado originalmente em buildcomcarlos.com.

An afternoon of iOS perf work, with Claude in the loop

Carloshperc — Fri, 08 May 2026 17:02:29 +0000

Subtitle: An iOS performance investigation I actually did, end-to-end through Claude Code, with MCP-driven simulator control, xctrace Time Profiler, and the Memory Graph CLI. What the AI handled, what it didn't, and how my workflow changed.

Hey folks, let me walk you through an afternoon I had debugging an iOS perf ticket I'd been postponing for three weeks. Motivations, obstacles, dead ends, and wins included.

Quick setup. Working on an app that uses SwiftUI quite a bit. The SavedItems tab was getting slow after about 15 location detail screens. Probably a memory leak. Probably something related to SwiftUI navigation. Probably "easy" after I stopped to analyze it. Spoiler: None of those hypotheses were correct.

The investigation took an entire afternoon and resulted in three independent corrections and three pull requests. And most of my time at the keyboard was spent reviewing what Claude had just done, not typing.

This text is not an account of how AI changed someone's life (please don't). It's a description of a workflow that I believe many mobile application engineers haven't yet experienced, with its friction points and parts that didn't work. If you work with iOS at a company, as an indie developer, or as a freelancer, this could be a valuable investment of a few hours (or minutes) in tools that will yield benefits when something on the device malfunctions.

The workflow, drawn out

The unusual feature of this diagram is that everything except the Developer node and the artifacts is accessible from a single chat session. Claude reads .memgraph files via leaks, controls the simulator through XcodeBuildMCP, and opens PRs via gh. My job is to (a) capture artifacts that require physical access to a device, (b) review proposed changes, and (c) ensure the integrity of the LLM.

The setup

Three tools, all pre-configured:

Claude Code in the terminal, pointing to the iOS repository.
XcodeBuildMCP, a Sentry Model Context Protocol server that exposes approximately 60 Apple development tools to LLM (build workspace, run in simulator, touch UI elements, capture screenshots, attach LLDB, stream logs). Installed via npm, with a single line of MCP client configuration.
xctrace, the CLI for Instruments. Logs Time Profiler traces on a physical device and exports them to XML, which LLM can parse. Plus the things macOS gives you for free: leaks, heap, vmmap, atos, xcrun simctl. The CLI tooling for iOS performance is a lot better than people think.

How it actually went

I'm going to describe what happened more or less in the order in which it occurred. Not a polished retrospective. The genuine story, including the dead end where I got lost for two hours before getting back on track.

Step 1. Reframing the problem (5 minutes)

I started the conversation with a short sentence: "Opening the SaveItems location details is slow after about 15 cycles." Claude consulted existing memory entries from previous sessions (project-specific information about the source code, file layout, and naming conventions) and immediately questioned the explanation: "Slow how? Memory leak, instance buildup? Or, in real time, does each opening seem to take longer?"

This is a useful first step. "Slow" is a symptom; the problem lies in retention (objects accumulating) or computation (task taking too long). There are different tools for each case. I described the symptom in observable terms: "after 15 openings, the next one takes about 6 seconds, and the Memory Graph shows 12 active instances of DetailViewModel after 12 cycles". And the path forked: investigate the leak first, as it is the simplest problem, and we have the ground truth (the Memory Graph has already shown us that the instances are not being released).

Step 2. Reproducing on the simulator, hands-off (10 minutes)

This is where MCP earns its keep. Claude built and ran the app on the iOS Simulator via a single tool called:

mcp__xcodebuildmcp__build_run_sim()

Next, I used the app: I tapped the Saved Items tab using the accessibility-adapted touch commands, tapped a location card, tapped back, tapped another card, and repeated the process. I captured screenshots between steps so the app could check (and so I could see in the chat history) what state it was in. There were about 12 opening/closing cycles without my interference.

With MCP running, I monitored the Xcode console and copied the relevant output to the chat. It's a bit worse than being fully automated, but it works.
By minute 30, we had a confirmed reproduction and ROOT CYCLE candidates from a Memory Graph file I'd exported and dropped on the Desktop.

Step 3. `leaks ~/Desktop/x.memgraph` (10 minutes that ended the leak)

Here's the part that ended a lot of speculation in two minutes. I exported a .memgraph from Xcode (Debug ➜ View Debugging ➜ Capture View Hierarchy ➜ Memory Graph ➜ File ➜ Export Memory Graph). Saved it to ~/Desktop/example-leaks.memgraph. Sent the path to Claude.

It ran:

leaks ~/Desktop/example-leaks.memgraph 2>&1 | grep -E "ROOT CYCLE|DetailViewModel" | head -40

And produced the chain:

ROOT CYCLE: SwiftUI._DictionaryStorage<AnyHashable, WeakBox<AnyLocationBase>>
  → TagIndexProjection<Int>
    → ForEachState<MediaGalleryItem...>
      → Closure context (.onImageSliderTap)
        → ._viewModel.wrappedValue → DetailViewModel
        → ._coordinator → DetailsCoordinator

That's a SwiftUI internal observation graph that holds a closure capturing self from inside a photo carousel ForEach with a .tag(Int) modifier on items. The closure was onImageSliderTap, passed into MediaCarouselHeaderView. It captured self strongly, which retained the entire view's @ObservedObject viewModel and @State coordinator backings forever.

I'd never seen TagIndexProjection<Int> before. Wouldn't have guessed .tag() caused this. The CLI told me directly. Without leaks, I would have spent another four hours auditing closures.

The fix was 15 lines. I hoisted handlePhotoTap to static, captured [weak viewModel, weak coord = self.coordinator] instead of relying on implicit self. Re-captured a fresh .memgraph. Zero ROOT CYCLEs containing my classes. Done. 🎉

Step 4. The dead end I'd have walked into anyway (90 minutes. Pause here.)

After the leak fix, the screen still felt slow. The next obvious hypothesis: fullScreenCover tears down the SavedItems' SwiftUI tree on dismiss, the parent re-renders a 50-cell grid with AsyncImages, that's why the next open is laggy.

Easy test: swap .fullScreenCover(item:) for .sheet(item:). One-line change. Ran it on the simulator, captured a fresh Memory Graph. Same slowness. Comparable counts. Hypothesis rejected.

This is where my workflow provided me with something I want to highlight specifically: my hypothesis was wrong, and the test cost 10 minutes instead of half a day. I changed one line, Claude recompiled, ran the simulator, captured the artifact, performed the analysis, and provided me with the results.

Reverting the change was easy (Git is wonderful). Total cost of the error: less than fifteen minutes. With a manual workflow, this experiment would have required an hour of work.

Step 5. Time Profiler, comparison-first (45 minutes)

The pivot: if presentation isn't the bottleneck, the cost has to be in the work each open does. I needed CPU samples.

xctrace Time Profiler against my iPhone, attached to the running app:

xcrun xctrace record \
  --template 'Time Profiler' \
  --device <UDID> \
  --attach DemoApp \
  --time-limit 90s \
  --output ~/Desktop/saveditems-tti-device.trace

I drove the device manually for 90 seconds. Same flow, six places opened and closed, plus scrolling. Then a second pass on Browse (the fluid baseline) for comparison.

I exported the time-profile schema of each .trace (this part of xctrace works via --xpath, unlike the Leaks data) to Claude, and it wrote a small analyzer in Python to count the frames that include the main thread and generated this side-by-side comparison:

Frame in `DemoApp` binary	Browse	SavedItems
`GraphQLClient.init`	7.7%	23.7%
`NetworkConnectivityChecker.init` ➜ `CTTelephonyNetworkInfo.init`	low	18.5%
`*Grid.body.getter`	9.9%	19.8%
`ActionsFactory.SavedItemsContext.make`	n/a	18.9%

According to the potential-freezes schema, SavedItems experienced 35 freezes lasting more than 250 ms in 90 seconds, totaling 21.97 seconds of freezing. Browse (another part of the application that uses the same components and some of the same structures; I used it for comparison) experienced 6 freezes, totaling 2.87 seconds. The main thread of SavedItems was hangs for 24% of the time during normal use.

The stack told a clean story. Every GridItemView body recompute was building fresh ItemActionsViewModel instances per cell, each one allocating a fresh GraphQLClient, each one allocating a fresh CTTelephonyNetworkInfo (a CoreTelephony class with a documented 30 to 100ms allocation cost on iOS). Multiply by N visible cells × every recompute. Main thread freezes everywhere.

Claude grepped the relevant factory file and found the smoking gun: four out of five *Context.make enums in ActionsFactory.swift use ViewModelCache.shared.getOrCreateViewModel(...). The fifth, SavedItemsContext.make, bypasses the cache and creates new VMs unconditionally.

Fix: A 50 lines mirroring the existing cache pattern in BrowseContext.make. This allowed me to recapture a trace using Time Profiler.

Metric	Before	After
Hangs >250ms	35	0
Total hang time	21.97s	0s
`GraphQLClient.init`	23.7%	7.9% (parity)
`CTTelephonyNetworkInfo.init`	18.5%	6.1% (parity)

🚀

Step 6. Stacked PRs and app-wide cleanup (30 minutes)

By this point, three independent fixes had emerged: the leak (a PR), the cache parity (a second PR added to the first), and a third that encompassed the entire application. Even after parity, both SavedItems and Browse were consuming about 6% of the main thread in CTTelephonyNetworkInfo.init, because the convenience init of GraphQLClient created a new NetworkConnectivityChecker each time. This NetworkConnectivityChecker should be a singleton across the entire application, not just in SavedItems.

Claude:

Used gh pr create --base feature/leak-fix-001 to stack PR #4406 on top of PR #4405.
Opened PR #4407 against dev directly (independent change).
Wrote each PR description with the before/after tables embedded. When the Time Profiler validation showed the cache fix alone was sufficient (the originally planned 5-step migration was no longer needed), it dropped the unnecessary steps from the PR scope.

I reviewed each PR and each commit message before it went out. The total typing I did on those was about 200 characters of confirmation. Everything was draft-ready.

What changed for me

A few things stand out, and they're not all positive.

The not-so-good first.

The CLI for iOS perf investigation is great, but it's brittle. xctrace --template Leaks --attach silently produces empty data due to a libmalloc not initialized error that you only see if you dig into a SQLite file inside the trace bundle. Some custom logging SDKs don't show in simctl log stream. SourceKit gets confused after tuist generate and reports false-positive errors. I had to know about all of these. Claude doesn't always. And the time savings depend on my catching the wrong path before going deep.

On the other hand, a lot of intuition in mobile engineering is also wrong, and the LLM is faster than I am at testing wrong intuitions. My hypothesis of .fullScreenCover ➜ .sheet was a wrong path that I would have followed even further without the cheap experimentation cycle. The retention cycle hypothesis I started with ("audit each closure looking for [weak self]") was also wrong.

The good.

Treating each artifact (.memgraph, .trace, screenshot) as a programmable input changes the loop. Memory Graph isn't "open Xcode and stare at the sidebar". It's leaks ~/path.memgraph 2>&1 | grep ROOT CYCLE piped through Python that an LLM can write inline. Time Profiler isn't "scrub through the timeline in Instruments GUI". It's xctrace export --xpath '/trace-toc/run/data/table[@schema="time-profile"]' and a 30-line parser. Once the artifacts are in CLI form, the LLM is genuinely useful.

The LLM is especially good at the boring parts. Writing a Python parser to fold thousands of stack frames into a top-20 inclusive table is exactly the kind of task it's fast at. Producing a side-by-side comparison table for a PR description with consistent formatting? Same. The stuff that's not intellectually hard but is attention-tax hard.

I keep memory entries in ~/.claude/projects/<repo>/memory/ for project-specific facts: the ViewModelCache pattern, the CTTelephonyNetworkInfo allocation-cost trap, and the SwiftUI TagIndexProjection pitfall. Next time someone (me or a colleague who picks up the workflow) starts a similar investigation, the LLM begins with that context instead of rediscovering it.

I also wrote a slash command, /perf-investigate, that captures the workflow as a checklist and rejects the natural temptations: don't propose architectural changes before a .memgraph or .trace exists, don't use xctrace --template Leaks --attach because it doesn't work, weak-capture only the closure proven by the memgraph to be the cycle root (not all of them). The slash command is the discipline that keeps me out of dead ends.

What I'd do differently

Three things.

Capture the "fluid" baseline first. When the symptom is "X feels slow", capture Time Profiler on X and on a sibling feature that's known to be fluid. The comparison is ten times more informative than the absolute numbers. I almost skipped the Browse baseline. That comparison was what made the cache-miss diagnosis irrefutable.

Resist sizing the ticket to the size of the original plan. I scoped the migration as a five-step refactor up front. The Time Profiler showed that step 1 alone closed the gap, and steps 2 to 5 were dropped. If your plan is "do A, then B, then C, then validate", validate after A and re-plan. Don't let the size of the original plan anchor the actual scope.

Memory Graph CLI is underused even by people who use the GUI version daily.
The Memory Graph debugger in Xcode is well known, but most devs never realize there are leaks, heap, and vmmap CLI tools that operate on .memgraph files and are fully scriptable. Combine that with an LLM in the loop, and you get a feedback cycle that most teams haven't tried.

I Packaged the Workflow

After this investigation, I sat down and transformed the manual parts into an MCP server, memorydetective. The first cut used 12 tools to cover the workflow above. By v1.8, it had grown to 31 tools, 34 catalog resources, and 5 Investigation Prompts covering the Instruments ecosystem.

v1.8 in particular was born from a real regression. On macOS 26.x, leaks --outputGraph aborts with Failed to get DYLD info for task whenever the target was not launched with MallocStackLogging=1. The new bootAndLaunchForLeakInvestigation absorbs build + boot + install + launch with the pre-propagated env var for capture to work out of the box, and captureMemgraph now returns a structured workaroundNotice pointing to the recordTimeProfile (Allocations) fallback when the regression hits anyway. The agent decides; The tools just stop lying about the failure mode.

memgraph analysis: analyzeMemgraph, findCycles, classifyCycle (which would have gotten the TagIndexProjection cycle in 30 seconds, with fix hint), findRetainers, diffMemgraphs, countAlive, reachableFromCycle
cycle-semantic CI gating: verifyFix, compareTracesByPattern
xctrace coverage: analyzeHangs, analyzeAnimationHitches, analyzeAllocations, analyzeAppLaunch, analyzeTimeProfile
macOS unified logging: logShow, logStream
capture + boot/launch: recordTimeProfile, captureMemgraph, bootAndLaunchForLeakInvestigation (single-call build + boot + launch with MallocStackLogging=1)
verify-fix loop: replayScenario (drives the simulator via tap/swipe/wait/type with a repeat count for leaks that only appear after N iterations), captureScenarioState (composite before/after snapshot: memgraph + screenshot + accessibility tree)
discovery: getInvestigationPlaybook, listTraceDevices, listTraceTemplates
retain-cycle visualization (Mermaid/DOT): renderCycleGraph
leak detection in XCUITest to run in CI: detectLeaksInXCUITest (experimental)
bridge with Swift source via SourceKit-LSP: swiftGetSymbolDefinition, swiftFindSymbolReferences, swiftSearchPattern, swiftGetSymbolsOverview, swiftGetHoverInfo

The cycle catalog covers SwiftUI (including Swift 6/@Observable/ SwiftData/NavigationStack), Combine, Swift Concurrency (including AsyncSequence-on-self), UIKit, Core Animation, Core Data, the Coordinator pattern, RxSwift, and Realm. Every classification carries a staticAnalysisHint pointing to the SwiftLint rule that would catch it in the parsing, or an explicit gap warning when there is no static rule. And a fixTemplate with a Swift before/after snippet that can be directly adapted.

It's Apache 2.0, it's on npm (memorydetective@1.8.0), and it works with Claude Code, Claude Desktop, Cursor, Cline, Kiro, and (experimentally) GitHub Copilot Agent mode.

Two ways to install. The classic MCP path:

npm install -g memorydetective

// ~/.claude/settings.json
{ "mcpServers": { "memorydetective": { "command": "memorydetective" } } }

Or, if you're on Claude Code, the same workflow ships as a one-command plugin install (no JSON edit, no global npm):

/plugin marketplace add carloshpdoc/memorydetective-plugin
/plugin install memorydetective@memorydetective-plugin

This plugin wraps the same MCP server memorydetective@^1.8 (pulled via npx under the hood) and also includes a slash command /perf-investigate with the built-in discipline checklist (don't propose architectural changes before memgraph or trace exists, don't trust xctrace --template Leaks --attach, weak-capture only the closure proven as the root of the cycle, etc.). Same workflow, less typing.

Then you ask the LLM something like "run leaks on ~/Desktop/myapp.memgraph and tell me what's leaking". The agent calls analyzeMemgraph ➜ classifyCycle and you receive a structured diagnosis with a fix hint. Or you can use it via the shell: memorydetective analyze ~/Desktop/myapp.memgraph.

What honestly isn't solid yet in v1.8.0: sample-level Time Profile analysis is still fragile (xctrace export of the time-profile schema crashes on heavy, non-symbolized traces; the tool surfaces a workaround). Hang, and animation-hitches analysis are rock-solid. The leaks --outputGraph regression on macOS 26.x is mitigated via bootAndLaunchForLeakInvestigation, but not 100% resolved (task_for_pid down there needs a fix from Apple); when the workaround fails, captureMemgraph surfaces a structured fallback for Allocations.

Memory Graph capture works for Mac apps + iOS simulator but not on physical devices (limitation of leaks(1), I can't fix it). replayScenario and the captureScenarioState UI tree sub-capture have a soft dependency on axe (brew install cameroncooke/axe/axe); the rest of the plugin works without it. detectLeaksInXCUITest is shipped but marked as experimental until real production runs validate the orchestration. The CHANGELOG is honest about all of this. See CHANGELOG.md.
GitHub: github.com/carloshpdoc/memorydetective. PRs welcome, especially new cycle patterns from real production leaks you've found.

If you want to try this

A short afternoon of setup gets you the whole workflow:

Install either via npm + MCP config (npm install -g memorydetective plus 1 line of JSON in your client) or, on Claude Code, via one-line plugin install: /plugin marketplace add carloshpdoc/memorydetective-plugin then /plugin install memorydetective@memorydetective-plugin.
Install Claude Code in the terminal if you haven't. Point it at one of your iOS projects.
(Optional, but recommended) Install XcodeBuildMCP for the simulator-driving parts. Pairs nicely.
Spend 20 minutes learning Memory Graph + leaks on a .memgraph you generate yourself. Pick a known retain cycle in your codebase, or build a tiny class A { var b: B } cycle in a playground and confirm leaks finds it. Then run memorydetective analyze on it and watch the cycle classified.
Pick a real perf ticket. Don't reach for the Xcode UI first.

The setup is small. The workflow is genuinely faster. The unfair advantage is that most of the iOS engineers I know haven't even tried this loop yet.

Wrapping up

Looking back, the afternoon broke down like this:

Wins

Three independent perf fixes shipped in one afternoon (one leak, one cache parity, one app-wide singleton).
Cost of being wrong dropped from "half a day per hypothesis" to "10 minutes per hypothesis". That single shift mattered more than any individual fix.
Memory Graph + leaks CLI gave me a precise retain chain in seconds, instead of four hours of closure-auditing.
PR housekeeping (descriptions, before/after tables, stack management) was off my plate.

Tradeoffs

The CLI tooling around iOS perf is brittle. Some templates silently produce empty data (xctrace --template Leaks --attach is the worst offender). You have to know the workarounds, and the LLM doesn't always.
LLM accepts proposing wholesale refactors of [weak self] that don't fix the leak (the real cycle is usually in only one closure, not all of them) and even introduce bugs that need fixing: closures that become silent no-ops, lost asynchronous work, races. In worse cases, re-strongification via guard let self recreates the cycle in a different way. Discipline (the slash command /perf-investigate) is what keeps you out of this hole: weak-capture only the closure proven by Memgraph as the root of the cycle, not all of them.
Some custom logging SDKs route around os_log, which means MCP-driven log capture won't see them. You fall back to pasting from Xcode.

What I'd repeat

Capture a "fluid" sibling feature as a baseline before reading any absolute numbers.
Validate after step 1 of any plan, then re-plan. Don't let the original size of a ticket anchor the real scope.
Treat artifacts (.memgraph, .trace) as programmable inputs, not GUI-only files.

And you, what does your iOS perf investigation flow look like today? Are you using the Memory Graph CLI, or staring at the Xcode sidebar? I'd love to hear what tooling actually moves the needle for you.

Thanks for reading, and until next time. 🚀

References

Memory Graph CLI (leaks, heap, vmmap, malloc_history, and .memgraph files)

[weak self] (mechanics, perf overhead, and re-strongification pitfalls)

A deep technical companion piece on the actual leak (a SwiftUI TagIndexProjection<Int> cycle through _DictionaryStorage<AnyHashable, WeakBox<AnyLocationBase>>, with the full retain chain and the wrong wholesale-[weak self] refactor I tried first) is coming next week. Different audience: pure technical, no AI workflow.

DEV Community: Carloshperc

AI agent memory you verify, not just trust

TL;DR

Who this article is for

The whole story in one line

The pain wasn't intelligence. It was memory.

The habit that masked the problem

There are two kinds of knowledge

What I wanted the memory to remember

Why I built it myself

The first version looked perfect

The day of the ghost session

The error was hidden in exit 0

Why silent failure is so deceptive

The investigation: follow the data, not intuition

Three bugs, all silent

Bug 1: control characters

Bug 2: the NUL byte

Bug 3: the echo that corrupted the JSON

Fixing the present was not enough

The pivot: the problem isn't remembering, it's verifying

The system changed personality

What the project does today

Before turning it into a startup, I stress-tested the thesis

What worked: daily use and real signals

Conclusion

Memória de agente de IA que você verifica, não só confia

TL;DR

Para quem é este artigo

A história inteira em uma linha

A dor não era inteligência. Era memória.

O hábito que mascarava o problema

Existem dois tipos de conhecimento

O que eu queria que a memória lembrasse

Por que construir em casa

A primeira versão parecia perfeita

O dia da sessão fantasma

O erro estava escondido no exit 0

Por que falha silenciosa é tão traiçoeira

A investigação: seguir o dado, não a intuição

Três bugs, todos silenciosos

Bug 1: caracteres de controle

Bug 2: o byte nulo

Bug 3: o echo que corrompia o JSON

Consertar o presente não bastava

A virada: o problema não é lembrar, é verificar

O sistema mudou de personalidade

O que o projeto faz hoje

Antes de virar startup, eu testei a tese

O que funcionou: uso diário e sinais reais

Conclusão

An afternoon of iOS perf work, with Claude in the loop

The workflow, drawn out

The setup

How it actually went

Step 1. Reframing the problem (5 minutes)

Step 2. Reproducing on the simulator, hands-off (10 minutes)

Step 3. leaks ~/Desktop/x.memgraph (10 minutes that ended the leak)

Step 4. The dead end I'd have walked into anyway (90 minutes. Pause here.)

Step 5. Time Profiler, comparison-first (45 minutes)

Step 6. Stacked PRs and app-wide cleanup (30 minutes)

What changed for me

What I'd do differently

I Packaged the Workflow

If you want to try this

Wrapping up

References

The error was hidden in `exit 0`

Bug 3: the `echo` that corrupted the JSON

O erro estava escondido no `exit 0`

Bug 3: o `echo` que corrompia o JSON

Step 3. `leaks ~/Desktop/x.memgraph` (10 minutes that ended the leak)