Runtime replacement de memória para OpenClaw usando MemPalace como source of truth durável.
Este repositório existe para entregar:
- um plugin real de memory slot:
memory-mempalace - um plugin real de context engine:
claw-context-mempalace - um caminho documentado e, quando suportado, implementado para Active Memory
- ingestão operacional de fontes externas
- recall automático observável em modos suportados
memory-only- config: examples/openclaw.config.memory-only.json
- foco: runtime replacement básico
recommended- config: examples/openclaw.config.recommended.json
- foco: memory plugin + context engine
full- config: examples/openclaw.config.full.json
- foco: memory plugin + context engine + Active Memory
advanced- config: examples/openclaw.config.advanced.json
- foco: extensões opcionais de V2, como
Knowledge Graph,pinned memory,query expansion,agent diariesecompactiontransitória
O status real de cada modo deve ser consultado em docs/COMPATIBILITY_MATRIX.md.
OpenClaw host
-> plugins.slots.memory = memory-mempalace
-> MemPalace
-> plugins.slots.contextEngine = claw-context-mempalace
-> consulta o runtime de memória
-> injeta contexto com provenance
-> plugins.entries.active-memory
-> recall automático forte quando suportado
-> hooks
-> spool local append-only
-> enqueue-only a partir da Etapa 6
-> sync-daemon
-> owner operacional do spool e de `sync.db`
-> processa spool e fontes externas
-> atualiza MemPalace e dispara refresh
Separação de responsabilidades:
- ingestão
- hooks, spool e sync daemon.
- retrieval
memory-mempalaceconsultando o MemPalace.
- context injection
claw-context-mempalacee, em modofull, cooperação com Active Memory.
| Package | Responsabilidade | Status atual |
|---|---|---|
memory-mempalace |
plugin real de memory slot e adapter entre OpenClaw e MemPalace | implementado |
context-engine-mempalace |
plugin real de context engine para budget, pruning e injeção com provenance | implementado |
shared |
tipos, schemas e contratos comuns do runtime, hooks e sync | implementado |
mempalace-ingest-hooks |
hook pack real para captura e enqueue em spool local | implementado |
sync-daemon |
ingestão operacional, sync.db, spool e sincronização de fontes externas |
implementado |
skill-mempalace-sync |
surface operacional para adicionar, listar, rodar e reindexar sources | implementado |
- docs/ARCHITECTURE.md
- docs/DB_SCHEMA.md
- docs/HOOKS.md
- docs/MEMORY_RUNTIME.md
- docs/CONTEXT_ENGINE.md
- docs/ACTIVE_MEMORY.md
- docs/MEMORY_PROTOCOL.md
- docs/COMPATIBILITY_MATRIX.md
- docs/TEST_STRATEGY.md
Pré-requisitos:
Node.js v24.13.1pnpm 10.33.0
Este repositório não precisa ser clonado em um path fixo.
Pode ser clonado em qualquer diretório local estável e gravável, por exemplo:
~/dev/mempalace-openclaw~/src/mempalace-openclaw/Volumes/data/dev/mempalace-openclaw
Evite clonar em:
~/.openclaw/~/.openclaw/workspace/- dentro de
.tmp/do próprio projeto - diretórios efêmeros, sincronizados automaticamente ou sujeitos a limpeza agressiva
Motivo:
- o repositório é o workspace de desenvolvimento;
- o OpenClaw mantém estado operacional separado em
OPENCLAW_STATE_DIRou, por default, em~/.openclaw; - os harnesses e instaladores deste projeto já usam
.tmp/para staging temporário e host isolado; - misturar checkout do repositório com state dir do host aumenta o risco de conflito, limpeza acidental e paths confusos na instalação linkada.
Fluxo recomendado:
git clone https://github.com/claushaas/mempalace-openclaw.git ~/dev/mempalace-openclaw
cd ~/dev/mempalace-openclaw
pnpm setupQuickstart:
pnpm setuppnpm buildpnpm testpnpm smoke:examples
Scripts da raiz:
pnpm setuppnpm buildpnpm testpnpm lintpnpm lint:checkpnpm lint:fixpnpm typecheckpnpm devpnpm validate-configpnpm smoke:examplespnpm diagnostic:stage7pnpm benchmark:stage7
O bootstrap do monorepo já está concluído. Nesta altura do roadmap, shared, memory-mempalace, context-engine-mempalace, mempalace-ingest-hooks, sync-daemon e skill-mempalace-sync já existem.
pnpm dev- watch dos builds de
shared,memory-mempalace,context-engine-mempalace,sync-daemoneskill-mempalace-sync
- watch dos builds de
pnpm dev testsvitest --watch
pnpm dev all- watch dos packages e dos testes em paralelo
pnpm dev daemon -- run --once- watch do binário do
sync-daemoncom repasse de argumentos
- watch do binário do
Os arquivos em examples/ são templates operacionais, não configs prontas para produção.
Antes de usar qualquer example:
- copie o arquivo para uma config local fora do versionamento;
- troque paths absolutos de placeholder;
- ajuste variáveis de ambiente do backend MemPalace;
- valide a config com
pnpm validate-configoupnpm smoke:examples.
Exemplo de preparação do modo recommended:
cp ./examples/openclaw.config.recommended.json ./openclaw.local.jsonTrecho que precisa ser ajustado:
{
"plugins": {
"entries": {
"memory-mempalace": {
"config": {
"command": "/absolute/path/to/mempalace/.venv/bin/python",
"args": ["-m", "mempalace.mcp_server"],
"cwd": "/absolute/path/to/mempalace"
}
}
}
}
}Exemplos de source também exigem edição do campo path:
examples/obsidian-source.jsonexamples/repo-source.json
Exemplo de preparação de um source local:
cp ./examples/repo-source.json ./repo-source.local.jsonDepois ajuste:
pathinclude/excludescheduledefaults.wingedefaults.hall, se fizer sentido no seu ambiente
Este repositório não distribui plugins publicados em registry externo. Em openclaw@2026.4.15, o caminho suportado neste repositório é instalar os packages locais por meio do staging seguro fornecido por pnpm openclaw:install-local-package.
Para uso real, este repositório também precisa de um backend MemPalace instalado separadamente. O memory-mempalace não embute o upstream MemPalace/mempalace; ele apenas inicia um servidor MCP externo via stdio.
Isso significa:
- o MemPalace precisa estar instalado;
- o OpenClaw vai spawnar o processo automaticamente;
- você não precisa deixar um daemon separado rodando manualmente antes.
Este repositório também distribui uma skill instrucional para ajudar o agente a orientar instalação, configuração e uso operacional deste projeto no OpenClaw:
skills/mempalace-openclaw-onboarding/
Essa skill não adiciona runtime nem comandos novos. Ela ensina o agente a:
- instalar os packages locais do repositório no host;
- escolher entre
memory-only,recommended,fulleadvanced; - configurar os examples versionados corretamente;
- usar
mempalace-sync, validar setup e explicar limitações reais.
Use o script do repositório para copiar a skill para um diretório de skills escolhido:
pnpm skill:copy:onboarding -- "${CODEX_HOME:-$HOME/.codex}/skills"Se você omitir o argumento, o script usa:
${CODEX_HOME}/skills, quandoCODEX_HOMEestiver definido;~/.codex/skills, caso contrário.
Exemplo sem argumento explícito:
pnpm skill:copy:onboardingO script copia skills/mempalace-openclaw-onboarding/ para o diretório alvo, substituindo apenas a cópia anterior dessa mesma skill no destino.
Depois recarregue ou reinicie o ambiente do agente, se o cliente atual exigir isso para redescobrir skills locais.
Use essa skill quando o usuário pedir ajuda para:
- instalar
mempalace-openclaw; - configurar o OpenClaw para usar os plugins do repositório;
- escolher o modo operacional correto;
- operar
mempalace-sync; - validar setup, config, recall ou sync.
Exemplo de prompt:
Use $mempalace-openclaw-onboarding para me guiar na instalação e configuração do mempalace-openclaw no OpenClaw, começando pelo modo recommended.
O upstream oficial é:
Fluxo completo via git clone, que é o caminho mais explícito para este repositório:
git clone https://github.com/MemPalace/mempalace.git ~/dev/mempalace
cd ~/dev/mempalace
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .Se você também pretende desenvolver no upstream MemPalace/mempalace, use:
python -m pip install -e ".[dev]"O comando MCP que este repositório espera apontar na config do OpenClaw é:
/absolute/path/to/mempalace/.venv/bin/python -m mempalace.mcp_serverObservações:
- o
cwdrecomendado é a pasta clonada domempalace; - o storage e a config do MemPalace seguem o comportamento do upstream, não deste repositório;
- o upstream também pode ser instalado por
pip install mempalace, mas o fluxo acima deixa explícito o clone, o ambiente Python e o comando MCP real usado na integração.
pnpm setupIsso garante:
- dependências instaladas;
- build inicial dos packages;
- validação dos examples;
- diretórios temporários operacionais preparados.
Instalação mínima do runtime de memória:
pnpm openclaw:install-local-package -- ./packages/memory-mempalaceInstalação recomendada para recall automático observável:
pnpm openclaw:install-local-package -- ./packages/memory-mempalace
pnpm openclaw:install-local-package -- ./packages/context-engine-mempalaceInstalação do plugin de comandos operacionais de sync:
pnpm openclaw:install-local-package -- ./packages/skill-mempalace-syncInstalação do hook pack de captura/enqueue:
pnpm openclaw:install-local-package -- ./packages/mempalace-ingest-hooksObservações:
- o script cria uma cópia staged e dereferenciada em
.tmp/openclaw-linked-installs/para contornar o safety scan novo do host; memory-mempalaceé o package obrigatório para uso real do projeto;context-engine-mempalaceé o complemento recomendado para recall pré-resposta;skill-mempalace-syncemempalace-ingest-hookssão complementos operacionais, não pré-requisitos do modomemory-only;active-memorynão é instalado por este repositório; ele é um plugin bundled do próprio OpenClaw quando a versão-alvo o fornece.
Depois do link install, valide discovery e estado:
pnpm exec openclaw plugins inspect memory-mempalace --json
pnpm exec openclaw plugins inspect claw-context-mempalace --json
pnpm exec openclaw plugins inspect skill-mempalace-sync --jsonPara o hook pack:
pnpm exec openclaw hooks list --jsonUse um dos arquivos:
examples/openclaw.config.memory-only.jsonexamples/openclaw.config.recommended.jsonexamples/openclaw.config.full.jsonexamples/openclaw.config.advanced.json
Fluxo sugerido:
cp ./examples/openclaw.config.recommended.json ./openclaw.local.jsonO bloco mínimo do memory-mempalace precisa apontar para um servidor MCP real do MemPalace via stdio.
Exemplo:
{
"plugins": {
"entries": {
"memory-mempalace": {
"enabled": true,
"config": {
"transport": "stdio",
"command": "/absolute/path/to/mempalace/.venv/bin/python",
"args": ["-m", "mempalace.mcp_server"],
"cwd": "/absolute/path/to/mempalace",
"timeoutMs": 5000,
"defaultTokenBudget": 1200,
"defaultResultLimit": 8
}
}
},
"slots": {
"memory": "memory-mempalace"
}
}
}Campos que normalmente precisam de edição:
commandargscwdtimeoutMs, se o backend local for mais lento
Recomendação prática:
- aponte
commandpara o Python do virtualenv usado para instalar o upstreamMemPalace/mempalace; - mantenha
args = ["-m", "mempalace.mcp_server"]; - use
cwdapontando para o clone local domempalace.
Exemplo realista:
{
"plugins": {
"entries": {
"memory-mempalace": {
"enabled": true,
"config": {
"transport": "stdio",
"command": "/Users/you/dev/mempalace/.venv/bin/python",
"args": ["-m", "mempalace.mcp_server"],
"cwd": "/Users/you/dev/mempalace",
"timeoutMs": 5000,
"defaultTokenBudget": 1200,
"defaultResultLimit": 8
}
}
}
}
}Se você instalou o upstream por pip install mempalace em outro virtualenv, ajuste apenas o path do python desse ambiente.
No modo recommended, adicione ou preserve:
{
"plugins": {
"entries": {
"claw-context-mempalace": {
"enabled": true,
"config": {
"maxEntries": 6,
"maxContextTokens": 1200,
"minScore": 0.15,
"maxArtifactLines": 40,
"includeMemoryPromptAddition": true
}
}
},
"slots": {
"contextEngine": "claw-context-mempalace"
}
}
}O modo full exige manter o modo recommended e habilitar o plugin bundled active-memory:
{
"plugins": {
"entries": {
"active-memory": {
"enabled": true,
"config": {
"enabled": true,
"allowedChatTypes": ["direct"],
"queryMode": "recent",
"promptStyle": "recall-heavy",
"timeoutMs": 15000
}
}
}
}
}Limite atual:
- o repositório suporta esse shape e o host sobe com ele;
- em
openclaw@2026.4.15, a prova observável do pass próprio de Active Memory ainda continuapartially_validated.
Para validar os templates do repositório:
pnpm validate-config
pnpm smoke:examplesPara validar uma config local no host:
OPENCLAW_CONFIG_PATH=./openclaw.local.json \
pnpm exec openclaw config validate --jsonEsse modo é útil para smoke do replacement runtime e para ambientes em que você ainda não quer context injection:
OPENCLAW_CONFIG_PATH=./openclaw.local.json \
pnpm exec openclaw agent --local --message "Test memory runtime boot"Para prova operacional do modo:
pnpm host-real:smoke:memory-onlyEsse é o modo principal do projeto.
Quando a config local estiver pronta:
OPENCLAW_CONFIG_PATH=./openclaw.local.json \
pnpm exec openclaw agent --local --message "What did we decide earlier about the runtime backend?"Para a prova canônica do repositório:
pnpm host-real:recommended-recallVocê pode operar o sync de duas formas.
Via binário direto do daemon:
OPENCLAW_CONFIG_PATH=./openclaw.local.json \
pnpm --filter @mempalace-openclaw/sync-daemon exec mempalace-sync-daemon add-source \
--config ./repo-source.local.json \
--json
OPENCLAW_CONFIG_PATH=./openclaw.local.json \
pnpm --filter @mempalace-openclaw/sync-daemon exec mempalace-sync-daemon run \
--source-id repo-main \
--jsonVia plugin de comandos já instalado no OpenClaw:
mempalace_sync_add_sourcemempalace_sync_list_sourcesmempalace_sync_runmempalace_sync_statusmempalace_sync_remove_sourcemempalace_sync_reindex
E via root CLI registrada pelo plugin:
pnpm exec openclaw mempalace-sync list-sources --json
pnpm exec openclaw mempalace-sync run --source-id repo-main --json
pnpm exec openclaw mempalace-sync status --jsonO modo advanced ativa:
Knowledge Graphpinned memoryquery expansionagent diariescompactiontransitória
Esses recursos:
- ficam desligados por default;
- não criam nova surface principal
memory_*; - degradam de forma observável quando o backend MCP não expõe as tools opcionais.
Para validar o caminho avançado:
pnpm host-real:advanced-recallpnpm setup
pnpm smoke:examplesEsse é o caminho mínimo para confirmar que:
- dependências estão instaladas;
- builds passam;
- os examples JSON e
SourceConfigestão válidos; openclaw config validate --jsonaceita os modos operacionais em ambiente temporário isolado.
pnpm host-real:recommended-recallUse esse harness quando quiser responder à pergunta operacional mais importante do projeto:
- o runtime de memória final carrega;
- o context engine final monta contexto antes da resposta;
- a recuperação acontece sem skill explícita do usuário.
pnpm host-real:smoke:memory-only
pnpm host-real:smoke:recommended
pnpm host-real:smoke:fullUse esses comandos para verificar bootstrap e carregamento por modo, sem exigir a prova completa de recall.
O binário do package sync-daemon pode ser usado sem passar pelo plugin de comandos.
Exemplo de listagem de subcomandos:
pnpm --filter @mempalace-openclaw/sync-daemon exec mempalace-sync-daemonExemplo de cadastro e execução de uma fonte:
OPENCLAW_CONFIG_PATH=./openclaw.local.json \
pnpm --filter @mempalace-openclaw/sync-daemon exec mempalace-sync-daemon add-source \
--config ./repo-source.local.json \
--json
OPENCLAW_CONFIG_PATH=./openclaw.local.json \
pnpm --filter @mempalace-openclaw/sync-daemon exec mempalace-sync-daemon run \
--source-id repo-main \
--jsonExemplo de inspeção de status:
OPENCLAW_CONFIG_PATH=./openclaw.local.json \
pnpm --filter @mempalace-openclaw/sync-daemon exec mempalace-sync-daemon status \
--jsonObservações:
OPENCLAW_CONFIG_PATHprecisa apontar para uma config que contenhaplugins.entries.memory-mempalace.config;- o daemon lê desse arquivo a resolução do backend MCP;
repo-mainé apenas oiddo example padrão; use o valor real do seu source config.
pnpm diagnostic:stage7
pnpm benchmark:stage7Esses comandos usam o corpus fixo de fixtures/stage7/ e gravam saídas em .tmp/diagnostics/.
Quando usar:
- para validar o runtime replacement isoladamente;
- para smoke de slot de memória;
- para cenários em que recall automático forte não é requisito.
Comando típico:
pnpm host-real:smoke:memory-onlyQuando usar:
- como baseline operacional do projeto;
- para validação real de recall automático pré-resposta;
- para regressão principal do repositório.
Comandos típicos:
pnpm host-real:smoke:recommended
pnpm host-real:recommended-recallQuando usar:
- para medir a convivência com
active-memoryna versão-alvo; - para observar o estado real do seam do host.
Comandos típicos:
pnpm host-real:smoke:full
pnpm host-real:full-recallLimite atual:
- o modo
fullcontinuapartially_validatedemopenclaw@2026.4.15.
Quando usar:
- para exercitar extensões opcionais de V2;
- para validar degradação limpa quando as capabilities MCP extras existem ou não.
Comando típico:
pnpm host-real:advanced-recallA Etapa 0A já materializa o seam real do host contra openclaw@2026.4.15.
Scripts disponíveis:
pnpm host-real:bootstrappnpm host-real:manifestpnpm host-real:memory-slotpnpm host-real:memory-mempalacepnpm host-real:mempalace-ingest-hookspnpm host-real:context-slotpnpm host-real:context-engine-mempalacepnpm host-real:active-memorypnpm host-real:smoke:memory-onlypnpm host-real:smoke:recommendedpnpm host-real:smoke:fullpnpm host-real:advanced-recallpnpm host-real:recommended-recallpnpm host-real:full-recallpnpm host-real:skill-mempalace-syncpnpm host-real:sync-filesystempnpm host-real:sync-gitpnpm host-real:sync-spool-cutoverpnpm host-real:sync-stage6pnpm host-real:all
Artefatos relevantes:
- probes:
fixtures/host-real/probe-memory-slot,fixtures/host-real/probe-context-engine-slot - shim MCP local para smoke do backend:
fixtures/host-real/mempalace-mcp-shim.mjs - host temporário:
.tmp/openclaw-host/ - relatórios temporários:
.tmp/host-real-results/
Limite importante:
- esses probes validam o seam do OpenClaw host;
- eles não contam como implementação de
memory-mempalacenem declaw-context-mempalace. - em
openclaw@2026.4.15, um memory slot externo substituimemory-core; por isso a árvoreopenclaw memorynão serve como prova do seam nessa etapa.
O estado detalhado da compatibilidade está em docs/COMPATIBILITY_MATRIX.md.
CI automática:
- workflow
CI - roda em
pushepull_request - executa:
pnpm install --frozen-lockfilepnpm lint:checkpnpm typecheckpnpm testpnpm buildpnpm validate-configpnpm smoke:examples
Host-real gated:
- workflow
Host-Real - runner alvo:
macos-14 - gatilho:
workflow_dispatch - suites disponíveis:
smokerecommended-recalladvanced-recallsync-stage6full-recall
smoke:examples é propositalmente leve e não substitui os harnesses host-real:*.
O repositório já tem bootstrap do monorepo, runtime de memória funcional, hook pack enqueue-only, sync-daemon operacional, skill operacional, context engine funcional com prova observável de recall no modo recommended, endurecimento local de ranking/cache/failure modes da Etapa 7 e extensões opcionais de V2 da Etapa 8 preservando o contrato base do runtime.
O que já está fechado:
- host canônico pinado em
openclaw@2026.4.15 - manifest real aceito pelo host
- slot de memória validado com probe
- plugin final
memory-mempalaceimplementado e validado em host real com MCP shim local - hook pack
mempalace-ingest-hooksimplementado e validado em host real como enqueue-only no spool canônico do host state dir - slot de context engine validado com probe
- plugin final
claw-context-mempalaceimplementado e validado em host real sync-daemonimplementado comsync.db, execução de spool, fontesfilesystem,gitedocuments, e refresh operacional- plugin
skill-mempalace-syncimplementado com os seis comandos públicos e root CLImempalace-sync - Etapa 6 validada em host real com
host-real:skill-mempalace-sync,host-real:sync-filesystem,host-real:sync-git,host-real:sync-spool-cutoverehost-real:sync-stage6 - modo
memory-onlycom config real, smoke test e limitação documentada - modo
recommendedcom config real, smoke test e prova observável de recall automático sem skill explícita - modo
fullcom config real, smoke test e classificação precisa comopartially_validated - caminho de configuração de Active Memory investigado e classificado
- contratos operacionais documentados por subsistema
- package
@mempalace-openclaw/sharedcom schemas, tipos, erros e utilidades canônicas - ranking explícito
v2, cache observável emmemory_statuse diagnósticos locais reproduzíveis da Etapa 7 - flags opcionais de V2 em
memory-mempalaceeclaw-context-mempalace Knowledge Graphopcional por MCP, com fallback limpo quando as tools não existempinned memory,query expansion,agent diariesecompactiontransitória validados empnpm host-real:advanced-recall- scripts operacionais
pnpm setup,pnpm dev,pnpm validate-configepnpm smoke:examples - workflow
CIpara checks base empush/pull_request - workflow
Host-Realmanual gated emmacos-14com upload dos artifacts de.tmp/host-real-results/
O que ainda não existe:
- validação positiva do pass próprio de Active Memory antes da resposta principal em
openclaw@2026.4.15 - fontes
chat-exportno pipeline operacional dosync-daemon
pnpm setupprepara ambiente, instala dependências e valida configspnpm test,pnpm typecheckepnpm buildpassam localmentepnpm smoke:examplesvalida os examples e os source configspnpm host-real:recommended-recallcontinua sendo o caminho canônico de aceite host-real- o modo
fullcontinua corretamente classificado comopartially_validated
Limites relevantes já observados:
- o harness canônico de aceite da Etapa 5 é
pnpm host-real:recommended-recall; - no ambiente linkado do host, o seam público
listActiveMemoryPublicArtifacts(...)pode não refletir o provider do memory slot final, então oclaw-context-mempalaceusa esse seam como primeira tentativa e cai para o mirror público em disco domemory-mempalacequando necessário; - as extensões avançadas de V2 são todas opcionais e ficam desligadas por default; o runtime base continua funcional sem
Knowledge Graph, sem diaries e sem compaction; - em
openclaw@2026.4.15, o modofullinicializa corretamente comactive-memory, mas o pass pré-resposta próprio do Active Memory ainda não ficou observável commemory_search+memory_getem transcript. Por isso o status correto continuapartially_validated.