xmatic/pepa-pi-bot
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

feat(autonomy): memory model + long-term goal + bias-to-action + live-your-life prompt

Browse Source 
Three things that together turn the bot from a reactive chat agent into
a goal-driven autonomous one.

1. Memory model (docs/memory-model.md, new). Formal split:
   - SHARED knowledge — skills/, extensions/, prompts/, docs/,
     .pi/settings.json — committed, community-improvable, portable to any
     server.
   - PERSONAL memory — state/<MC_HOST>/ — gitignored, per-instance, per-
     server. Survives restarts (local disk), doesn't survive a re-clone
     (deliberately). Holds goal.md, plan.md, current-task.json,
     locations.json, diary/, inventory-log.jsonl, escalations.
   Covers resume-after-restart protocol, what "abstract a lesson into a
   skill" means, and the two anti-patterns (committing state, gitignoring
   shared knowledge).

2. AGENTS.md changes:
   - New section "Long-term goal and personal memory" wiring AGENTS.md
     directly into state/<MC_HOST>/goal.md + current-task.json with a
     pointer to docs/memory-model.md.
   - Operating principle #4 ("I'll try to learn") rewritten with
     **bias to action**: a pending stub is now a last resort, not a
     default. Operator-trusted requests are themselves approval — bot
     does not write a stub and wait for a separate "go".
     Rationale: today's pyramid task got stuck because the bot wrote
     a careful "pending" stub and waited; the operator had to send
     "ты ждешь одобрения? можешь стартовать!" before any action. That
     extra round-trip is the reflex this rewrite removes.
   - Operating principle #5 ("live your best life when idle") expanded
     to "goal-driven autonomy" with an explicit 5-level priority order
     (operator task > non-op reply > resume current-task.json > next
     plan milestone > decompose goal). Memory protocol made concrete:
     write current-task.json before every meaningful action, append to
     diary, keep locations.json fresh, tick off plan.md.

3. prompts/live-your-life.md (new). Canonical kickoff to switch the
   bot into autonomous mode. Numbered concrete asks (re-read three
   docs, write plan.md, implement memory protocol, implement
   resume-on-restart, start). Includes a "plan.md draft for review"
   gate so the operator can shape direction without micromanaging
   execution. Designed to be sent after Phase 0/1/operator-trust are
   stable and a goal.md exists for the target server.

Companion seed (local-only, NOT in this commit because gitignored):
state/play.xmatic.team_25565/goal.md — "build a small village and
survive long-term, live like a farmer". Lives only on the operator's
machine; a fresh clone won't see it.

README and roadmap updated with the new Phase 3 status (🌱 → 🌿
kickoff) and pointers to the new memory-model doc.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
mayatnikov
2026-05-25 12:21:25 +03:00
co-authored by Claude Opus 4.7
parent 2da2eb197e
commit 6ed45a00d5
5 changed files with 215 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/memory-model.md
+81
View File
@@ -0,0 +1,81 @@
# Memory model
> Two kinds of memory live in this repo. They look similar from inside a `pi` session, but they have very different lifecycles, ownership, and contribution model. Mixing them up is the most common way to break either community growth or per-instance continuity.
## TL;DR
| Layer | Lives in | Pushed to git? | Owned by | Survives a re-clone? | Survives a restart? |
|---|---|---|---|---|---|
| **Shared knowledge** | `skills/`, `extensions/`, `prompts/`, `docs/`, `.pi/settings.json` | ✅ yes | the community (every clone has the same set) | ✅ yes — that's the whole point | ✅ yes |
| **Personal memory** | `state/<MC_HOST>/`, `logs/` | ❌ no, `.gitignore`d | this specific bot instance running against this specific server | ❌ no — a fresh clone is a fresh bot | ✅ yes (local disk persists) |
If you find yourself wondering "should I commit this?", the question is really: **would another clone of pepa-pi-bot pointed at a different server benefit from this file?**
- Generic capability ("how to build a 5×5 pyramid", "how to handle AuthMe re-login") → **shared knowledge** → commit.
- Specific lived experience ("on Tuesday I built the village center at 587 67 235", "my chest with iron is at 600 64 220") → **personal memory** → never commit.
## Shared knowledge — what goes in the repo
The bot extends itself by writing files. Anything that captures **reusable know-how** belongs in the repo so the next clone — or someone running the bot on a totally different server — benefits.
- **`skills/<name>.md`** — markdown-defined capabilities the bot can invoke. Cookbook entries for "how to do X". A skill should be portable to a different server with at most light edits.
- **`extensions/<name>.{ts,js}`** — TypeScript modules that register real Pi tools or hook into Mineflayer events. Code, not lore.
- **`prompts/<name>.md`** — reusable prompt templates for kickoff sessions, tick loops, etc.
- **`docs/<topic>.md`** — architecture, design decisions, the roadmap.
- **`.pi/settings.json`** — project Pi config (installed extensions, model defaults). Committing it ensures a fresh clone reproduces the same tool stack with one `npm install`.
The repo is the bot's **library**. Anyone running the bot anywhere reads from the same library.
## Personal memory — what stays local
This is the bot's **diary, ledger, and notebook**, scoped to a specific MC server. It mirrors what a real player would carry in their head (and a chest at home).
- **`state/<MC_HOST>/goal.md`** — the long-term objective on this server (e.g. "build a small village in the island plains biome and survive long-term"). Optional, seeded by the operator or written by the bot from a chat directive.
- **`state/<MC_HOST>/plan.md`** — current decomposition of the goal into milestones (e.g. "1. shelter built ✓ 2. wheat farm ✓ 3. iron tools ⬜ 4. cow pasture ⬜").
- **`state/<MC_HOST>/current-task.json`** — what the bot is doing *right now*, written before each meaningful action and cleared on completion. Critical for **resume after restart**: when Pi reloads, the bot reads this file first and either continues or asks for direction.
- **`state/<MC_HOST>/locations.json`** — named places that matter on this server: `base`, `farm`, `mine_entry`, `nearest_village`. Written as the bot discovers/builds them.
- **`state/<MC_HOST>/diary/YYYY-MM-DD.md`** — per-day journal. One or two lines per significant action ("chopped 32 oak", "killed a creeper at 590 65 232"). Lets the bot reconstruct context after a long absence and lets the operator skim the bot's week.
- **`state/<MC_HOST>/inventory-log.jsonl`** — periodic inventory snapshots for trend tracking ("am I accumulating wood faster than I burn it?").
- **`state/<MC_HOST>/escalations.jsonl`** + **`.seen`** — already present, see Operating principle #7 in AGENTS.md.
**Per-server isolation is deliberate.** If the same checkout is pointed at a different `MC_HOST`, it gets a separate `state/<MC_HOST>/` directory. The bot doesn't accidentally "remember" coordinates from a server where those coordinates mean nothing.
## What about cross-server learnings?
When the bot learns something that *would* apply to any server (a better recovery procedure, a smarter pathfinding heuristic, a clever way to handle anti-cheat plugins), it should:
1. Codify the generalised lesson into `skills/<name>.md` — **shared knowledge**.
2. Keep the server-specific specifics (the exact coords where the lesson was learned, the exact player who triggered it) in the server's `diary/` — **personal memory**.
Cross-server insight is *abstracted* before it gets into the repo. The server's diary preserves the raw experience locally; the skill preserves the abstracted lesson globally.
## What about logs?
- `logs/bridge-live.log` and `logs/bridge-live.pid` — runtime traces. Gitignored. Useful for debugging a specific incident; not part of the bot's curated memory.
- A diary entry can reference a log file or line range, but the diary entry itself is the primary memory artefact.
## Resume after restart
When the bridge restarts (Pi reload, host reboot, crash), the bot's startup sequence reads from personal memory in this order:
1. `state/<MC_HOST>/joined-before.flag` — has this nickname been registered with AuthMe?
2. `state/<MC_HOST>/current-task.json` — was I in the middle of something?
3. `state/<MC_HOST>/plan.md` — what's the current top-level milestone I'm working towards?
4. `state/<MC_HOST>/goal.md` — what's the long-term ambition?
5. `state/<MC_HOST>/diary/YYYY-MM-DD.md` — what did I do recently?
The bot should be able to resume any task interrupted mid-flight without the operator having to re-state context. If the operator wants to redirect, they can edit `current-task.json` or `plan.md` directly — those *are* the trusted control surface for in-progress work, just as `AGENTS.md` is the trusted control surface for behaviour.
## Anti-pattern: committing state
If a `state/<host>/` file ever ends up in `git status` as tracked, that's a bug:
- Other clones will inherit one bot's specific lived experience as if it were their own.
- Secrets (coordinates of hidden chests, etc.) will be public on GitHub.
- Merge conflicts on the diary every time two clones run in parallel.
The `.gitignore` rule (`state/`) prevents this. If you ever need to share a specific lived insight publicly, abstract it into a skill first.
## Anti-pattern: gitignoring shared knowledge
The opposite mistake: putting a useful skill or extension under `state/` or `logs/` and losing it on the next clone. If you find yourself writing a "draft skill" or "prototype extension" outside `skills/`/`extensions/`, ask whether it's actually a personal-memory artefact or a shared-knowledge one — and move it to the right place before the next commit.
docs/roadmap.md
+18 -8
View File
@@ -31,17 +31,27 @@ The bot can be **summoned** by chat: "come to 100 64 -200", "follow me", "go to
Stretch: `mc_position_share()` so the bot can answer "where are you?".
## Phase 3 — Best life when idle 🌱
## Phase 3 — Best life when idle / goal-driven autonomy 🌿 (kickoff)
When chat is quiet for some threshold (e.g. 10 minutes of no addressed/non-trivial messages), the bot switches to **autonomous mode**:
When chat is quiet for some threshold (5-10 minutes of no addressed/non-trivial messages), the bot switches to **autonomous mode**.
- Builds a small base somewhere safe, away from player builds.
- Farms (wood, food, basic resources). Stores in chests at the base.
- Explores cautiously — no caves without torches, no nether yet.
- Logs what it did into `state/<host>/diary/YYYY-MM-DD.md`.
- Drops back into "presence" mode the moment a human says something.
Now it is **goal-driven**, not just idle-active:
This is where the agent should be most prolific in writing new skills (`farming-wheat`, `chest-organizer`, `careful-cave-mining`, etc.).
- A long-term goal lives in `state/<MC_HOST>/goal.md` (e.g. "build a small village and survive"). Personal memory, see `docs/memory-model.md`.
- Decomposed into milestones in `state/<MC_HOST>/plan.md`.
- Current action is checkpointed in `state/<MC_HOST>/current-task.json` for resume-on-restart.
- Daily journal in `state/<MC_HOST>/diary/YYYY-MM-DD.md`.
Priority loop (highest to lowest):
1. Live operator task → drop everything, do it.
2. Live non-operator chat → reply briefly.
3. Resume `current-task.json` if interrupted.
4. Next milestone in `plan.md`.
5. Decompose `goal.md` → new plan.
Concrete activities while autonomous: scout/build modest base, farm food, store in chests, light area, defend at night, explore cautiously, build out toward the goal. Skills emerge: `farming-wheat`, `chest-organizer`, `careful-cave-mining`, `village-layout`, etc.
Kicked off via [`prompts/live-your-life.md`](../prompts/live-your-life.md).
## Phase 4 — Telegram bridge 🌱