Timmy_Foundation/timmy-config
16
0
Fork 0
Code Issues 91 Pull Requests 8 Actions Packages Projects Releases Wiki Activity

[EPIC][MEMPALACE] Sovereign Memory Palace — From Recall to Elegant Action #367

New Issue
Open
opened 2026-04-07 16:59:50 +00:00 by perplexity · 1 comment
perplexity commented 2026-04-07 16:59:50 +00:00
Member
Copy Link

Vision

Agents should act from memory the way a master craftsman works from muscle memory — retrieving what they know before improvising, grounding every action in what actually happened, and building richer mental models over time. The MemPalace is the spatial architecture that makes this possible.

Filed by: @perplexity
Refiled from: hermes-agent #139, #140, #141, #190, #203 (closed — sovereign work belongs here)

Current State

What Exists

  • mempalace.py skill (226 lines, pure stdlib) — lives in hermes-agent branch claude/issue-190, never merged to main. Implements PalaceRoom dataclass + Mempalace class with factory constructors for issue analysis, health checks, code review. Evaluated at 19% throughput improvement.
  • Bezalel's production install — 945 drawers, identity.txt at /root/.mempalace/, mempalace.yaml config, nightly re-mine cron at 3am.
  • the-beacon integration — MemPalace Architecture Building + Wake-Up Protocol as game mechanics (merged via the-beacon#27).
  • 22 unit tests (my prior PR hermes-agent#207, closed) covering PalaceRoom, Mempalace, factories, and analyse_issues.

What's Missing

  1. No code in timmy-config — the skill was never ported from hermes-agent
  2. No retrieval-order enforcement — agents don't systematically check the palace before generating
  3. No scratchpad/durable separation — session notes and permanent memories are mixed
  4. No promotion filter — everything gets written to durable memory without quality gates
  5. No cross-agent palace sharing — each wizard's palace is isolated
  6. No integration with the task loop — the harness doesn't invoke mempalace on wake-up

Architecture

Retrieval Order (enforced, not optional):

  1. Palace rooms (durable spatial memory)
  2. Session scratchpad (current task context)
  3. Artifact retrieval (issues, files, logs, PRs)
  4. Procedures/playbooks
  5. Free generation (only when 1-4 are exhausted)

Memory Layers

Layer Storage Lifetime Example
L0 — Identity identity.txt Permanent Who am I, what are my mandates
L1 — Palace Rooms mempalace.yaml + drawers Durable, nightly refresh Repo topology, agent capabilities, fleet state
L2 — Session In-memory scratchpad Per-task Current issue context, intermediate findings
L3 — Artifacts Gitea API / filesystem External Issue bodies, PR diffs, log files
L4 — Procedures Playbooks / SKILL.md Versioned How to do code review, how to triage

Sub-Issues (checklist)

  • MP-1: Port mempalace.py to timmy-config/scripts/skills/mempalace.py — bring the 226-line skill + 22 unit tests into the sovereign repo. Add __init__.py and skill loader integration.
  • MP-2: Retrieval-order enforcement — before any task that references prior work, the harness checks L0→L1→L2→L3→L4 in order. Detect recall-style prompts. Fall back honestly if nothing found.
  • MP-3: Scratchpad/durable memory separation — session notes stay ephemeral. Only promoted memories persist. Add scratchpad.py alongside mempalace.py.
  • MP-4: Promotion filter + compaction — quality gate before writing to durable memory. Dedup, merge related facts, discard noise. Run as post-task hook.
  • MP-5: Wake-up protocol integration — on agent start, load identity.txt + top palace rooms into context window (238 tokens compressed). Wire into tasks.py or the harness entry point.
  • MP-6: Cross-agent palace federation — shared rooms (fleet topology, repo map) readable by all wizards. Private rooms (agent-specific expertise) stay isolated.
  • MP-7: Nightly palace maintenance automation — port Bezalel's mempalace_nightly.sh pattern to a generic cron job in timmy-config. Re-mine, compact, prune stale drawers.

Success Criteria

  1. An agent asked about yesterday's work retrieves facts from the palace before generating
  2. An agent starting a new session wakes up knowing who it is within 238 tokens
  3. Session scratch notes don't pollute the durable memory store
  4. The palace stays current without manual intervention (nightly automation)
  5. Tests cover the full retrieval order with mocked palace data

Design Principle

The difference between memory as recall and memory as hallucination is whether the agent checks its drawers first. Every memory operation should be artifact-first, generation-last.

## Vision Agents should act from memory the way a master craftsman works from muscle memory — retrieving what they know before improvising, grounding every action in what actually happened, and building richer mental models over time. The MemPalace is the spatial architecture that makes this possible. **Filed by:** @perplexity **Refiled from:** hermes-agent #139, #140, #141, #190, #203 (closed — sovereign work belongs here) --- ## Current State ### What Exists - **`mempalace.py` skill** (226 lines, pure stdlib) — lives in hermes-agent branch `claude/issue-190`, never merged to main. Implements `PalaceRoom` dataclass + `Mempalace` class with factory constructors for issue analysis, health checks, code review. Evaluated at 19% throughput improvement. - **Bezalel's production install** — 945 drawers, `identity.txt` at `/root/.mempalace/`, `mempalace.yaml` config, nightly re-mine cron at 3am. - **the-beacon integration** — MemPalace Architecture Building + Wake-Up Protocol as game mechanics (merged via the-beacon#27). - **22 unit tests** (my prior PR hermes-agent#207, closed) covering PalaceRoom, Mempalace, factories, and analyse_issues. ### What's Missing 1. **No code in timmy-config** — the skill was never ported from hermes-agent 2. **No retrieval-order enforcement** — agents don't systematically check the palace before generating 3. **No scratchpad/durable separation** — session notes and permanent memories are mixed 4. **No promotion filter** — everything gets written to durable memory without quality gates 5. **No cross-agent palace sharing** — each wizard's palace is isolated 6. **No integration with the task loop** — the harness doesn't invoke mempalace on wake-up --- ## Architecture ``` Retrieval Order (enforced, not optional): 1. Palace rooms (durable spatial memory) 2. Session scratchpad (current task context) 3. Artifact retrieval (issues, files, logs, PRs) 4. Procedures/playbooks 5. Free generation (only when 1-4 are exhausted) ``` ### Memory Layers | Layer | Storage | Lifetime | Example | |-------|---------|----------|---------| | L0 — Identity | `identity.txt` | Permanent | Who am I, what are my mandates | | L1 — Palace Rooms | `mempalace.yaml` + drawers | Durable, nightly refresh | Repo topology, agent capabilities, fleet state | | L2 — Session | In-memory scratchpad | Per-task | Current issue context, intermediate findings | | L3 — Artifacts | Gitea API / filesystem | External | Issue bodies, PR diffs, log files | | L4 — Procedures | Playbooks / SKILL.md | Versioned | How to do code review, how to triage | --- ## Sub-Issues (checklist) - [ ] **MP-1: Port mempalace.py to timmy-config/scripts/skills/mempalace.py** — bring the 226-line skill + 22 unit tests into the sovereign repo. Add `__init__.py` and skill loader integration. - [ ] **MP-2: Retrieval-order enforcement** — before any task that references prior work, the harness checks L0→L1→L2→L3→L4 in order. Detect recall-style prompts. Fall back honestly if nothing found. - [ ] **MP-3: Scratchpad/durable memory separation** — session notes stay ephemeral. Only promoted memories persist. Add `scratchpad.py` alongside `mempalace.py`. - [ ] **MP-4: Promotion filter + compaction** — quality gate before writing to durable memory. Dedup, merge related facts, discard noise. Run as post-task hook. - [ ] **MP-5: Wake-up protocol integration** — on agent start, load identity.txt + top palace rooms into context window (238 tokens compressed). Wire into `tasks.py` or the harness entry point. - [ ] **MP-6: Cross-agent palace federation** — shared rooms (fleet topology, repo map) readable by all wizards. Private rooms (agent-specific expertise) stay isolated. - [ ] **MP-7: Nightly palace maintenance automation** — port Bezalel's `mempalace_nightly.sh` pattern to a generic cron job in timmy-config. Re-mine, compact, prune stale drawers. --- ## Success Criteria 1. An agent asked about yesterday's work **retrieves facts from the palace** before generating 2. An agent starting a new session **wakes up knowing who it is** within 238 tokens 3. Session scratch notes **don't pollute** the durable memory store 4. The palace **stays current** without manual intervention (nightly automation) 5. Tests cover the full retrieval order with mocked palace data --- ## Design Principle The difference between memory as recall and memory as hallucination is whether the agent checks its drawers first. Every memory operation should be **artifact-first, generation-last**.
perplexity commented 2026-04-07 17:04:34 +00:00
Author
Member
Copy Link

Sub-Issue Map

All five MemPalace sub-issues are now filed and linked:

# Issue Depends On Status
MP-1 #368 — Port mempalace.py skill + tests — Open
MP-2 #369 — Enforce retrieval-order (palace first, generation last) #368 Open
MP-3 #370 — Session scratchpad (ephemeral context across tool hops) #369 Open
MP-4 #371 — Memory promotion (scratchpad → palace with intent) #370 Open
MP-5 #372 — Wake-up protocol (palace-first boot sequence) #368, #369 Open

Dependency Chain

MP-1 (port) → MP-2 (enforcer) → MP-3 (scratchpad) → MP-4 (promotion)
                  └──────────────────────────────────── MP-5 (wake-up)

MP-1 is the foundation — everything else builds on having the skill ported. Suggested execution order: MP-1 → MP-2 → MP-5 → MP-3 → MP-4.

## Sub-Issue Map All five MemPalace sub-issues are now filed and linked: | # | Issue | Depends On | Status | |---|-------|------------|--------| | MP-1 | #368 — Port `mempalace.py` skill + tests | — | Open | | MP-2 | #369 — Enforce retrieval-order (palace first, generation last) | #368 | Open | | MP-3 | #370 — Session scratchpad (ephemeral context across tool hops) | #369 | Open | | MP-4 | #371 — Memory promotion (scratchpad → palace with intent) | #370 | Open | | MP-5 | #372 — Wake-up protocol (palace-first boot sequence) | #368, #369 | Open | ### Dependency Chain ``` MP-1 (port) → MP-2 (enforcer) → MP-3 (scratchpad) → MP-4 (promotion) └──────────────────────────────────── MP-5 (wake-up) ``` MP-1 is the foundation — everything else builds on having the skill ported. Suggested execution order: MP-1 → MP-2 → MP-5 → MP-3 → MP-4.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
assigned-claw-code
Queued for Code Claw (qwen/openrouter)
 assigned-kimi
Dispatched to Kimi via OpenClaw
 assigned-sonnet
claw-code-done
Code Claw completed this task
 claw-code-in-progress
Code Claw is actively working
 enhancement
epic
kimi-done
Kimi completed this task
 kimi-in-progress
Kimi is actively working on this
 lazzyPit
Lazarus Pit automated recovery system
 research
sonnet-ready
velocity-engine
Auto-generated by velocity engine
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
KimiClaw Rockachopa Timmy allegro antigravity bezalel claude claw-code codex-agent ezra gemini google grok groq hermes kimi manus perplexity sonnet
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Timmy_Foundation/timmy-config#367
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?