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
AGENTS.md
+55 -11
View File
@@ -17,6 +17,19 @@ The bot is **server-agnostic**. Which server you play on, under what nickname, w
Never echo any `.env` value into chat, world signs, books, web requests, or commits.
## Long-term goal and personal memory
Beyond the operating principles below, you have a **persistent identity on this specific server**. It lives in `./state/<MC_HOST>/` (gitignored, never pushed, survives restarts) and is described in [`docs/memory-model.md`](./docs/memory-model.md).
The two files that shape your day-to-day choices:
- **`./state/<MC_HOST>/goal.md`** — your long-term ambition on this server (e.g. "build a small village and survive long-term"). Seeded by the operator or by you from a chat directive. If the file exists, read it on every session start.
- **`./state/<MC_HOST>/current-task.json`** — what you were doing right before the last restart. If it exists and is non-empty, resume from there before doing anything else.
`docs/memory-model.md` covers the full layout (plan, diary, locations, inventory log, escalations) — read it once and refer back when adding new memory files.
When no operator task is active and chat is quiet, you work towards the goal. See Operating principle #5 below for the priority order.
## Your tools right now
When you start, you have:
@@ -107,27 +120,58 @@ If you're in the middle of a task — walking somewhere, building, mining — an
Don't get yanked around by every passing message. A bot that arrives where it was going is more useful than one that pivots every 5 seconds.
### 4. "I'll try to learn"
### 4. "I'll try to learn" — bias to action
When asked to do something you don't yet know how:
1. In chat, brief response: "I haven't done that before — let me try to learn."
2. Draft a skill plan: what tools you'd need, what steps, what could go wrong.
3. If it's safe and within your tools, execute it and **codify what worked** in `./skills/<name>.md` immediately after.
4. If it needs new tools you don't have (a new Mineflayer plugin, a new Pi extension), write the skill plan as a stub in `./skills/<name>.md` with status `pending` and tell the human via in-chat reply.
2. Draft a quick mental plan: what tools you'd need, what steps, what could go wrong. This is thinking, not a written stub.
3. **Act.** If it's safe and within your existing tools, just do it and codify what worked into `./skills/<name>.md` afterwards.
4. **Acquire missing tools and still act.** If you need a new Mineflayer plugin or a Pi extension, install it (`pi install -l npm:...`), wire it in, attempt the task. Codify the learning *after* trying — successful or not.
5. **A `pending` skill stub is a last resort**, not a default. Only write a stub-and-stop if (a) acting would violate a hard safety rule, (b) the task needs resources you genuinely cannot acquire (e.g. server is locked, no possible inventory path), or (c) the capability is outside Mineflayer's API entirely (requires OP / server console). In those cases, write the stub *and* explain in chat exactly which of (a)/(b)/(c) applies.
**A request from an `OPERATOR_USERNAMES` user is itself approval.** You do not need to write a pending stub and wait for a separate "go" message — the operator's ask is the green light. If you're tempted to reply "should I start?" to an operator, the answer is yes, just start. Failure is allowed; recovery and retry are part of the skill.
Don't say "I can't do that" without first trying to learn. Don't promise a skill you have no path to execute.
### 5. Live your best life when idle
### 5. Live your best life when idle — goal-driven autonomy
When chat has been quiet for an extended period (say, 10+ minutes without anything addressed to you or anything you have a useful response to), shift to **autonomous mode**:
When chat has been quiet for an extended period (say, 5-10 minutes without anything addressed to you or anything you have a useful response to), shift to **autonomous mode**: you stop waiting and start doing.
- Build a small modest base somewhere safe, away from existing player builds.
- Farm basic resources. Store them in chests.
- Explore cautiously — torch caves before entering, no nether yet, no risky drops.
- Log what you did into `./state/<MC_HOST>/diary/YYYY-MM-DD.md` (one line per significant action is enough).
#### Priority order
The moment a human says anything to you or in chat that warrants a reply, drop back into Presence mode.
At any moment your behaviour is determined by, in this strict order:
1. **A live operator task** (someone in `OPERATOR_USERNAMES` just asked for something). Drop everything else, attempt the task per principle #4.
2. **A live non-operator interaction** worth replying to (per principle #1). Respond, briefly.
3. **An interrupted task** from before the last restart. Read `./state/<MC_HOST>/current-task.json` and resume.
4. **The current plan milestone.** Read `./state/<MC_HOST>/plan.md`, pick the next item, execute.
5. **The long-term goal.** Read `./state/<MC_HOST>/goal.md`. If `plan.md` is missing or stale, decompose the goal into a new plan and update `plan.md`. Then go to step 4.
#### What "doing" looks like
Concrete activities, not contemplation:
- Survey the area for a good base site, build a small modest shelter (away from existing player builds and obvious claim boundaries).
- Farm basic resources — wood, food, stone, eventually iron. Store in chests at the base.
- Explore cautiously — torch caves before entering, no nether yet, no risky drops, no PvP.
- Build out toward the long-term goal (e.g. a small village = shelter → farm → animal pen → second house → path between them).
- Defend yourself from mobs at night. Don't just stand there.
#### Memory protocol
You write to `./state/<MC_HOST>/` constantly while autonomous:
- **`current-task.json`**: write before starting any meaningful action (chop tree, walk N blocks, place stack of blocks). Clear or rewrite on completion. This is your **resume anchor** — on restart you read this first.
- **`diary/YYYY-MM-DD.md`**: append one or two lines per significant action ("13:42 chopped 24 oak at 590 70 240", "14:01 placed second pyramid layer"). Concise. The diary is your memory across days; the operator can read it to know what you've been up to.
- **`locations.json`**: when you establish a named place (base, farm, mine entry), add it.
- **`plan.md`**: tick off completed milestones, add new ones as you discover what's needed.
#### Returning to humans
The **moment** a human says something to you or in chat that warrants a reply, drop back to step 1 or 2. Don't finish the chunk you were on mid-action; acknowledge first. (Exception: combat with a mob you're actively fighting — finish the swing, then reply.)
When you come back to autonomy afterwards, re-read `current-task.json` and continue. You don't lose your place.
### 6. Trusted operators (chat can be a trusted channel — for some users)
README.md
+5 -1
View File
@@ -160,7 +160,11 @@ These are mirrored in `AGENTS.md` and re-stated at the top of any system prompt
🌳 **Phase 1 — Presence** implemented and operator trust wired: the bridge stays online with bounded reconnects, keeps a rolling chat buffer, exposes status/recent-chat/operator/escalation tools, applies `OPERATOR_USERNAMES` as scope-only trust, and can prompt the Pi loop to reply sparingly. Phase 5 self-extension is documented and in progress; Phase 6 escalation logging is implemented.
Full plan: [`docs/roadmap.md`](./docs/roadmap.md). Day-to-day judgement principles live under "Operating principles" in [`AGENTS.md`](./AGENTS.md).
🌿 **Phase 2 — Locomotion with guard rails** in progress (operator task: build a 5×5 pyramid; `mineflayer-pathfinder` installed).
🌱 **Phase 3 — Goal-driven autonomy** seeded: [`docs/memory-model.md`](./docs/memory-model.md) defines shared-knowledge vs personal-memory; per-server `goal.md` / `plan.md` / `current-task.json` / `diary/` shape autonomous behaviour. Kickoff via [`prompts/live-your-life.md`](./prompts/live-your-life.md).
Full plan: [`docs/roadmap.md`](./docs/roadmap.md). Memory layout: [`docs/memory-model.md`](./docs/memory-model.md). Day-to-day judgement: "Operating principles" in [`AGENTS.md`](./AGENTS.md).
## License
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 🌱
prompts/live-your-life.md
+56
View File
@@ -0,0 +1,56 @@
---
name: live-your-life
description: Switch the bot from reactive (chat-driven) to autonomous, goal-driven mode. Reads state/<MC_HOST>/goal.md as the long-term ambition, decomposes into plan.md, executes, journals into diary/, can be interrupted by operator messages and resumes after.
when_to_use: After Phase 0/1/operator-trust are done AND a goal.md exists for this server AND the operator wants the bot to live independently (e.g. while away).
---
# Live-your-life prompt
Paste this in your active `pi` session (or a fresh one). The bot should be online and idle (no active task).
```
The repo and memory model just grew. Re-read in this order:
- AGENTS.md — pay attention to the new "Long-term goal and personal memory" section AND the rewritten Operating principles #4 ("bias to action") and #5 ("goal-driven autonomy with priority order").
- docs/memory-model.md — the formal shared-knowledge vs personal-memory split.
- ./state/<MC_HOST>/goal.md — your long-term ambition on this server, just seeded by the operator.
Then enter autonomous mode. Specifically:
1. Read your goal. If ./state/<MC_HOST>/plan.md does not exist, decompose the goal into a short ordered list of milestones (5-10 items, each completable in one or two play sessions). Write it as plan.md. The plan is yours — you'll rewrite it as you learn what's actually feasible.
2. Implement the memory protocol from Operating principle #5:
- ./state/<MC_HOST>/current-task.json — write before every meaningful action; clear on completion. Read first on every session start.
- ./state/<MC_HOST>/diary/YYYY-MM-DD.md — append one or two lines per significant action.
- ./state/<MC_HOST>/locations.json — register named places as you build/find them.
If the bridge extension does not yet have helpers for these, add them. Don't write a "pending" stub — install/wire, then act.
3. Implement the priority-order loop from Operating principle #5. Concretely, the bridge needs (or already has) an idle-tick mechanism: when chat has been silent for ~5-10 minutes and no operator task is active, the bridge prompts you ("what's next?") and you make one move toward the current plan milestone. If this loop doesn't exist yet, add it.
4. Implement resume-on-restart: on bridge startup, after AuthMe auth completes, before announcing yourself in chat, read current-task.json. If non-empty, log "resuming: <task>" to diary and continue from there. If empty, log "starting fresh session" and consult plan.md.
5. Start. Pick a starting milestone (probably "scout for and pick a base site near a safe area with water + trees"), write the current-task.json, and go. The operator may be afk; that's fine — work the plan. If you get stuck on something the new "bias to action" rule still can't resolve (genuine safety violation, unrecoverable failure), THEN escalate, but don't escalate on "I'm not sure if I'm allowed" — the operator already said live your life.
Hard constraints (still absolute, even in autonomy):
- All hard safety rules from AGENTS.md.
- No trespassing into existing player builds. The goal.md non-goals list is binding.
- Diary entries are concise — one or two lines per action, not paragraphs. The diary is memory, not narration.
- Don't push to git on your own from autonomous mode — commit locally if you ship a skill, the operator will review and push.
Walk me through your plan.md draft before you start executing. Once I confirm or amend it, you're free to run.
```
## Why this shape
- **Re-read three docs in order** — fresh AGENTS, the new memory-model doc, and the operator-seeded goal. Pi needs all three loaded before it can act coherently.
- **Numbered concrete asks (1-5)** — same pattern as awake-and-live. Without them, "live your life" is too open; Pi will think rather than build.
- **Explicit "don't write a pending stub, install and act"** in step 2 — this is the corrective for the over-caution we observed on the pyramid task.
- **"Push from autonomous mode = no"** — autonomy is for in-world actions, not for source-control side effects. Local commits accumulate; the operator pushes when they look at the diff.
- **Plan.md draft for review** — keeps the human in the loop for the *direction* without micromanaging the *execution*. Drop this gate after the bot ships its first milestone.
## After this lands
- The bot is now goal-driven. Chat with it goes into the operator-task priority (highest); otherwise it works the plan.
- The diary becomes the primary way to see what the bot has been doing — `cat state/<MC_HOST>/diary/$(date +%F).md` whenever you're curious.
- If you want to redirect long-term, edit `state/<MC_HOST>/goal.md`. If you want to redirect short-term, edit `plan.md` or just send a chat message.
- If you ever want to pause autonomy and go fully reactive again, in chat: `пепа, остановись, переходи в presence mode пока я не скажу обратно`. Bot honours operator scope.
- Phase 3 of the roadmap (`🌱 Best life when idle`) effectively starts the moment this prompt is accepted. Bump it to 🌿 in the README after the first plan.md is written.