petit-poucet

Leaves pebbles so your coding agents find their way back.

In the French tale Le Petit Poucet, a boy drops white pebbles along the path so he can find his way home. petit-poucet does the same for AI coding agents: it keeps a small, curated memory of your rules, decisions and verified facts, and every agent you switch between starts each session with it.

Works with Claude Code, GitHub Copilot (CLI, VS Code, IntelliJ, the Copilot app), Codex, Cursor, Antigravity CLI, OpenCode, omp and Hermes Agent, on macOS, Linux and Windows.

Why

Coding agents forget everything between sessions, and each keeps its own memory in its own format: what you taught Claude Code on Monday, Codex doesn't know on Tuesday. petit-poucet gives them one memory that:

• follows you across agents: one command wires the same memory into every agent it finds;
• is there from the first message: a session-start hook hands the agent your rules, so nothing depends on the model deciding to look;
• is yours to read: plain Markdown in a folder you choose, browsable in Obsidian, with every change in git;
• is curated: agents save a decision or a verified fact on purpose, with its source, and rules you stated change only with your confirmation;
• stays clean: checks and a cleanup review catch duplicates, stale facts and unused notes.

How it compares with the agents' own memory: comparison.

Install

Ask your agent. Paste this into Claude Code, Codex, Copilot or any agent with a shell:

Install petit-poucet for me: follow https://areguig.github.io/petit-poucet/install.md

The guide tells it what to run, how to check, and what to tell you: which agents to restart. It also updates an older install.

Or by hand:

# macOS, Linux
curl -fsSL https://raw.githubusercontent.com/areguig/petit-poucet/main/install.sh | sh
petit-poucet setup

# Windows, in PowerShell
irm https://raw.githubusercontent.com/areguig/petit-poucet/main/install.ps1 | iex
petit-poucet setup

Then restart your agents. To update later: petit-poucet update; session start tells you when a release is out. Already keeping memory elsewhere? Ask your agent to run the migrate-memory skill. Details, per-agent notes and settings: install and set up.

What your agent sees

At the start of every session, the agent gets your rules and an Index of what applies here: your preferences and the current repo's notes, one line each. It opens only the notes a task needs.

🪨 petit-poucet · 20 notes loaded (preferences + chargepath-api)

## Preferences (all repos)
- [[Preferences/commit-rules]] — commit locally per step, 1-2 line message, never push
- [[Preferences/never-read-secrets]] — use secret values only by piping them into commands, never print them

## Projects / chargepath-api
- [[Projects/chargepath-api/prod-db-no-postgis]] — the prod database has no PostGIS: spatial queries must work without it

On several machines

Share one memory between your machines with Syncthing, peer to peer and without a cloud: install it, then pair the machines with petit-poucet sync, one command on each side. Step by step: several machines.

Learn more

• Install and set up: agents, settings, Obsidian, migrating
• Several machines: sharing the vault through Syncthing
• Reference: the vault, the note format, tools, skills, commands
• How it works: session start, the cleanup review, the checks, usage across machines
• Compared with built-in memory
• Contributing: building, testing, releasing

Acknowledgements

Ideas borrowed from Basic Memory, IWE and okf-agent-memory. Built with Claude Code.

License

Apache-2.0