How it works
Small binary, plain files.
For the curious: what happens in a session, how the memory stays clean, how machines share it, and where everything lives.
01 / in a session
Three moments, one 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 or a release is out.
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.
02 / 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
--- type: feedback # user | feedback | project | reference scope: all repos summary: commit locally per step, 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.
A project is recognised by its git remote first, so a checkout in another folder, or on another machine, still matches; a folder without a remote matches by its name. Each note is one short fact with its source.
03 / 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.
every save
Checked
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.
the whole vault
Found
Near-duplicates, notes naming files gone from the repo, notes nobody opened for months, summaries too long, sessions loading too many notes. petit-poucet check lists them.
cleanup
Reviewed
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.
session start
Reminded
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.
04 / several agents, several machines
No clobbering, full history.
- Agents at once. Agents running together take turns through a vault lock, so none loses another's write.
- Every change in git. A local commit you can inspect or undo; nothing is ever pushed.
- Machines, through Syncthing.
petit-poucet syncpairs them, peer to peer. Notes changed on another machine are committed at the next session start, each machine keeping its own history. - Conflicts, merged with you. When two machines change a note at once, Syncthing keeps both; your agent is told, merges them with you, and deletes the copy.
- Usage counted per machine. Which notes are read, and where, is recorded inside the vault, so the cleanup knows what is used everywhere.
05 / 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 |
06 / go deeper
The details.
for agents
Install guide
What an agent runs to install or update petit-poucet, how it checks, and what it tells you.
setup
Install and set up
What setup writes for each agent, the install options, updating, Obsidian, migrating old memory.
sync
Several machines
Installing Syncthing, pairing, what syncs and what stays on each machine, conflicts.
internals
Architecture
The files in the vault, usage across machines, how the review is sized, how near-duplicates are found.