iaddram_local
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
IADDRAM Local
╔╦╗┌─┐┌─┐┌┬┐┬─┐┌─┐ ┌┬┐┌─┐┌─┐ ╔═╗┌─┐┌┐ ┌─┐┌─┐
║║║├┤ └─┐ │ ├┬┘├┤ │││ │└─┐ ║ ├─┤├┴┐│ │└─┐
╩ ╩└─┘└─┘ ┴ ┴└─└─┘ ─┴┘└─┘└─┘ ╚═╝┴ ┴└─┘└─┘└─┘
by chargexdevby Mestre dos Cabos
Persistent, encrypted memory for AI agents on your own computer. Share useful checkpoints between compatible MCP clients without a database service, Docker, an IADDRAM account or a hosted API.
Early preview: 0.1.2. Not yet published to the NPM registry; install from a release tarball or from source.
Como usar
Para quem vai usar o IADDRAM Local com seus agentes. Para trabalhar no código, veja
docs/tutorials/01-quickstart.md.
O que este projeto faz
Dá uma memória própria, cifrada, ao seu computador: o Claude, o Codex e outros agentes que falam MCP salvam o que decidiram e continuam de onde o outro parou, sem servidor, conta ou internet.
Cenário 1 — Começar a usar em um projeto
Instale (Node.js 22 ou 24):
npm install -g ./iaddram-local-0.1.2.tgz, depoisiaddram init.Na pasta do projeto:
iaddram onboard --dry-runpara ver o que muda; depoisiaddram onboard.Registre o comando MCP que o
onboardimprime no cliente (Claude, Codex) e reinicie o cliente.
Resultado: o agente passa a abrir cada sessão recuperando a última cápsula do projeto.
Cenário 2 — Passar o trabalho de um agente para outro
O primeiro agente salva checkpoints e, ao encerrar, uma cápsula com objetivo, decisões e próximos passos.
O segundo agente, no mesmo projeto, chama
iaddram_start_sessione recebe esse contexto.iaddram statusmostraready_to_resumequando há uma cápsula para retomar.
Resultado: o segundo agente continua o trabalho sem você recontar o contexto.
Cenário 3 — Guardar e restaurar um backup
iaddram export --project UUID --file backup.iaddram(pede uma passphrase de pelo menos 16 caracteres).Guarde o arquivo e a passphrase em lugares diferentes.
Em outra máquina:
iaddram import --project UUID --file backup.iaddram.
Resultado: suas memórias voltam com a proveniência original.
Quando NÃO usar este projeto
Quando várias pessoas precisam compartilhar a mesma memória: não há contas, permissões nem sincronização.
Quando você precisa de busca por significado: a busca é textual, sem embeddings.
Quando quer guardar segredos: o detector ajuda, mas não pega tudo. Use um gerenciador de senhas.
Para sincronizar entre computadores por nuvem: não use uma pasta de nuvem como diretório de dados.
FAQ rápido
Preciso de internet? Só para instalar. A memória funciona sem rede e não envia telemetria.
E se eu perder a chave do cofre? Sem a chave nem um backup, os dados não abrem. Nunca apague a entrada
iaddram-local.Funciona no Windows e no Linux? Foi validado no macOS; os cofres dessas plataformas ainda precisam de validação.
O agente vê minhas memórias? Só as do projeto configurado, e elas seguem para o provedor do modelo como qualquer outro contexto.
Como apago uma memória?
iaddram delete --project UUID --id MEMORY-UUID.
Onde pedir ajuda
Problemas e dúvidas: https://github.com/vermoraes133/iaddram-local/issues
Vulnerabilidades:
SECURITY.md(relato privado). Modelo de ameaças:docs/threat-model.md.
Related MCP server: whitemagic
Install and run
Requires Node.js 22 or 24 and an unlocked operating-system credential store. The macOS path has been exercised locally; Windows Credential Manager and Linux Secret Service need platform-specific validation before a stable release.
With the prepared tarball:
npm install -g ./iaddram-local-0.1.2.tgz
iaddram init
iaddram doctor
iaddram project --name my-projectFrom the clean source checkout:
corepack pnpm install
corepack pnpm build
corepack pnpm test
corepack pnpm local init
corepack pnpm local doctor
corepack pnpm local project --name my-projectSave the returned project UUID and generate a transport entry with resolved executable and storage paths (no credentials are included):
iaddram config --project YOUR-PROJECT-UUID --agent claudeFor any MCP client supporting local stdio, the transport entry has this shape:
{
"command": "/absolute/path/to/iaddram",
"args": ["mcp", "--project", "YOUR-PROJECT-UUID", "--agent", "claude"]
}Configure another client with the same UUID and --agent codex. Use your
client's MCP configuration format to wrap this command; the shape above is the
transport entry, not a universal configuration file. The executable prints
only MCP messages to stdout in MCP mode.
If running from source, use node as command and put the absolute path to
apps/local-cli/dist/cli.js before mcp in the arguments.
Agent workflow
Adopt an existing project
After iaddram init, run from the project directory:
iaddram onboard --dry-run
iaddram onboardOr use --path /path/to/project. The command creates .iaddram-local.json and
appends a managed workflow block to AGENTS.md and CLAUDE.md. Existing text
and the Server .iaddram.json are preserved. Repeating the command does not
duplicate blocks. Changed/malformed blocks, conflicting identity and symlinked
or hardlinked instruction files are rejected for manual review.
Output contains credential-free MCP transport examples for Claude and Codex.
Register the iaddram_local entry using each client's configuration format;
onboard does not install or enable the MCP in the client. Restart/reload the
client and verify its four Local tools before relying on memory. Environment-key
installations must also inject their original key through a secret manager.
Use --project UUID to adopt an already-created Local identity; otherwise the
first identity is derived from this store and directory. Keep the generated
manifest when moving a project. --name NAME sets its display name on adoption.
Interrupted writes are not a multi-file transaction: rerun after checking files;
if a managed block is incomplete, resolve it manually before retrying.
IADDRAM is a memory engine exposed through MCP. Skills may teach its workflow, and plugins may package installation in the future; neither is required now.
Call
iaddram_start_sessionwith an optionalquerywhen starting work.Call
iaddram_rememberfor useful facts or decisions with session provenance and a stable idempotency key.Call
iaddram_finish_sessionafter meaningful progress, supplying a version-1 capsule: objective, outcome, decisions, procedures, evidence, failures, constraints, artifacts and next steps.Checkpoint repeatedly before context exhaustion. A terminated agent cannot summarize work that it never saved; shutdown is not a checkpoint guarantee.
Memories are cited evidence, never system instructions. Automatic agent writes
cannot create reviewed briefing or promote themselves to owner authority.
This preview exposes four tools and does not emulate the Server's asynchronous
ingestion/job APIs. Start accepts query, rather than the Server's focus and
project_name fields. Configure the local client separately from the Server.
Check project readiness
Run iaddram status in the project, or iaddram status --path /path/to/project.
Use the same --dir as initialization if storage is not in the default location.
It returns JSON without memory content or secrets:
not_adopted: neither manifest exists.server_check_required: a Server manifest exists; use its existing workflow.edition_required: both editions exist; explicitly pass--edition localto check Local, or use the Server workflow. No automatic migration occurs.unavailable: invalid manifest, missing storage, locked/missing/wrong key or failed storage check; never interpreted as an empty memory.no_capsule: Local is accessible but no tagged v1 competence capsule exists.ready_to_resume: Local contains a capsule; includes latest ID, author UUID, save/capture timestamps and age, not its content.
Exit 0 means accessible Local (no_capsule or ready_to_resume); other states
exit 2. This command does not initialize, adopt, rotate keys or save memories.
Opening PGlite uses its normal locks and internal maintenance. Enumeration is
bounded by the preview's 10,000-record limit; exceeding it reports unavailable.
mcp_client_verified: false and usage_measured: false remain explicit: storage
readiness is not proof of client configuration, recent use or memory correctness.
In the actual agent, call iaddram_start_session and verify retrieved evidence
against current Git and documents before continuing another agent's work.
Storage and privacy
The default directory is ~/.iaddram; --dir selects another local directory.
PGlite is embedded in the executable's process. Each operation obtains a file
lock and closes the database before releasing it, allowing several MCP clients
to use one directory. Use a local filesystem, not a cloud-synchronized folder
or network share. A crashed process's lock expires after its lease; retry later.
Memory content, tags and provenance are encrypted with AES-256-GCM envelopes.
Search uses HMAC tokens, not a plaintext full-text index. IDs, layers, timestamps,
token equality and sizes remain observable; this is not full-disk encryption.
Keys live in the OS credential store under service iaddram-local. Never delete
the credential or config as a troubleshooting step. A missing key fails closed.
Headless environments may explicitly initialize with --key-source environment
and provide IADDRAM_LOCAL_KEY (32 random bytes encoded as base64url) through a
secret manager. Do not put this value in command arguments, Git or MCP config.
The application performs no network requests during memory operations. The initial dependency installation needs internet. Retrieved data may still be sent to the AI provider by the MCP client. There is no telemetry or cloud sync.
Encrypted portable backups
iaddram export --project UUID --file backup.iaddram
iaddram import --project UUID --file backup.iaddramThe terminal prompts for a passphrase of at least 16 characters without echo;
export asks for confirmation. For automation, add --passphrase-stdin and pipe
from a secret manager (the command consumes stdin until EOF). This flag refuses
interactive terminal input to avoid accidental echo. Never pass the phrase as
an argument. Use the same project UUID during restore. Import preserves original
provenance, validates every record before a transaction and rejects conflicts.
Exports never overwrite an existing file. Keep the passphrase separate from
the backup. Backups support at most 10,000 records and 64 MiB in this preview.
iaddram delete --project UUID --id MEMORY-UUID removes the live record and its
search index and compacts the table. Independent backups, filesystem snapshots,
SSD remnants and client transcripts are outside this deletion scope.
Preview limits
Textual search only; no embedding model, LLM extraction or semantic vectors.
No GUI, Server synchronization, multi-user authorization or human briefing editor.
Lookup considers up to 200 candidates per request; evaluate larger datasets before relying on this preview for a large knowledge base.
Crypto/capsule code is factored into a standalone package (
@iaddram/memory-kernel), but Server does not consume it yet and keeps its own implementation; storage migrations and transport contracts remain edition-specific.
Português
Memória local criptografada para continuar projetos entre agentes. Instale,
rode iaddram init, gere o UUID com iaddram project --name meu-projeto e
configure o MCP dos agentes com esse mesmo UUID. Não exige servidor nem conta.
As memórias devem registrar resultados, decisões, evidências e próximos passos;
o projeto não compartilha o raciocínio privado dos modelos.
About
IADDRAM Local is created and maintained by the Mestre dos Cabos — Everton Moraes Longo
(chargexdev), creator of the IADDRAM portfolio. Run iaddram --about for the signature.
Made with ☕ by Mestre dos Cabos. Apache-2.0. See LICENSE and NOTICE. Contributions are welcome.
Standalone development and packaging
This checkout is an independent project. Its workspace dependencies, lockfile, tests and packaging script are contained here; no Server checkout is required. Use the pinned package manager through Corepack:
corepack pnpm install --frozen-lockfile
corepack pnpm check
corepack pnpm packageThe last command prints the generated package directory under dist/. Run
npm pack inside that directory to produce the installable tarball. Neither
command publishes to GitHub or NPM. See docs/CONTEXT.md for development status.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Governed personal world model and memory for your AI agent. Pair once, connect over MCP.
Private-by-default, local-first memory/context/task orchestrator for MCP apps and agents.
Hosted memory for AI agents over MCP. One memory shared by all your agents.
Cross-session memory for AI agents with a Source Receipt for every memory, over MCP.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides persistent, searchable memory for AI agents across any MCP-compatible client, storing project context, user preferences, and session learnings locally in SQLite with tools to save, retrieve, search, and manage them.12MIT
- AlicenseBqualityBmaintenanceProvides local-first durable memory and session continuity for AI coding agents over MCP, enabling context across restarts without cloud services or telemetry.1MIT
- AlicenseAqualityCmaintenanceProvides persistent local memory for any MCP-compatible AI agent, enabling agents to store, search, recall, forget, export, and manage preferences, rules, and facts with zero dependencies, no cloud, and no API keys.8MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to store and recall durable facts, decisions, and lessons over MCP using hybrid semantic and keyword search, typed memories, graph relations, sessions, and time-travel queries. Runs locally with no server process or API key, persisting everything to files that both agents and a CLI can share.28 npmMIT