petit-poucet

How it works

For the curious: what happens in a session, how the memory stays clean, and where everything lives.

Install Home GitHub

In a session

Three moments, one small binary

Session start

A hook gives the agent the memory rules and the Index of what applies here: your preferences and the current repo's notes, one line each. You see a pebble line, and a reminder when a cleanup is due.

While you work

Through MCP tools, the agent opens only the notes a task needs, searches, and saves new facts on purpose, each with its source. Every change is checked, rewrites the Index and makes a local git commit.

Cleanup

Ask to tidy your memory: a read-only subagent reviews the notes and the problems code found, and proposes merges, fixes and deletions. Your agent applies only what you confirm.

The vault

Plain files, in three places

~/agent-memory/
├─ Index.md            generated from the notes' summaries
├─ Preferences/        your rules for every repo, loaded in every session
├─ Projects/<repo>/    a repo's notes, loaded in that repo
└─ Topics/<topic>/     no repo (a homelab, a server…), searched on demand

A project is recognised by its git remote first, then its folder name. Each note is one short fact with its source:

---
type: feedback            # user | feedback (a rule you stated) | project | reference
scope: all repos
summary: commit locally per step, 1-2 line message, never push
created: 2026-09-14
tags: [agent-memory, git]
---

# Commit rules

Commit each finished step locally; never push.

**Why:** the user said so on 2026-09-14.
**How to apply:** after each step.

Staying clean

Code finds the problems, you decide the fixes

A memory is only useful if it stays right. petit-poucet checks what code can check, and leaves the judgement to an agent and to you.

Checked on every save

A valid type, a one-line summary, a source; secrets refused; links kept whole when notes move. A rule you stated changes only with your OK, and an edit you made meanwhile is never overwritten.

Found across the vault

Near-duplicates, notes naming files gone from the repo, notes nobody opened for months, summaries too long, and sessions loading too many notes. petit-poucet check lists them.

Reviewed by an agent

Up to 300 notes, every cleanup reviews them all. Above that, your preferences, the folders that changed and the ones you use come first; ask for a whole review any time.

Reminded at session start

When many notes changed or a month went by since the last cleanup, the session-start line says so. Nothing cleans up behind your back.

Several agents, several machines

No clobbering, full history

Agents running at once take turns through a vault lock, so none loses another's write. Every change is a local git commit you can inspect or undo; nothing is ever pushed. Which notes are read, and where, is counted per machine inside the vault, so the cleanup knows what is used. Keeping one vault in sync across machines (Syncthing or git) comes next.

Settings

One file, every value in sight

~/.config/petit-poucet/config.toml holds the vault's path and every limit, with its value. A setting added by a newer version is written in with its default, keeping your own lines.

Setting	Default	What it does
`full_review_max_notes`	300	up to this many notes, every cleanup reviews every note
`review_max_pages`	10	above that, how many pages a cleanup review fills
`active_days`	30	folders used within this many days come first in a big vault's review
`unused_days`	90	a note untouched and unread for this long is listed as unused
`summary_max_chars`	200	longer summaries are flagged
`index_max_notes`	100	a session loading more notes is flagged
`cleanup_reminder_notes`, `cleanup_reminder_days`	30, 30	when session start reminds of a cleanup

Go deeper