Intuition

Memory for an agent that lives in Pi or OMP. Facts are lines in a git repo. The agent searches them and quotes them back. Nothing else is loaded into the prompt.

Install

One command, in either host:

omp install intuition-pi
# or
pi install git:github.com/Shixuuu/intuition

That is the whole install. The extension runs the CLI from the installed package files, so there is no pip install step. On first run it creates ~/memory and appends a marked memory block to the host's AGENTS.md (~/.omp/agent/AGENTS.md or ~/.pi/agent/AGENTS.md), so every session is told to search before answering about you. Set INTUITION_STORE to keep the store somewhere else. Set INTUITION_BIN to use an intuition binary instead of the bundled copy. Needs Python 3.11 or newer and git on PATH.

The block lives between intuition-memory markers, so updates replace it instead of piling up, and your own words above and below it are never touched. To turn memory off, remove the package (omp plugin uninstall intuition-pi, or the pi remove equivalent) and delete the block.

What the agent gets

Three tools, registered by extensions/intuition/index.ts.

• memory_search takes a question in your words and returns at most 4 current fact lines. No match returns nothing.
• memory_note saves one fact: who or what it is about, one sentence, and the words it came from. It refuses an external preference and evidence it cannot resolve.
• memory_close ends a fact. It appends a line. The old line stays.

On the first turn of a session the extension adds one rule to the system prompt: search before answering about you, save what is durable, and say you do not know when search is empty. Later turns do not repeat it. After a compaction it is added once more. The hook never searches on its own.

Without Pi or OMP, a shell agent runs intuition rule and follows it with intuition search and intuition note.

The CLI

Every command takes --store. Without it, the store is $INTUITION_STORE or ~/memory.

intuition init [--no-sample] [path]   # create a store; --store is respected
intuition search "who is the PM for Lighthouse" [--as-of 2026-09-01] [--type person]
intuition note --type person --name June --text "PM for Lighthouse" \
  --evidence "Shixu said so" --since 2026-08
intuition close --target f-20261008T125754Z-58c4 --until 2026-10-08
intuition undo                          # reverts the latest note: or close: commit
intuition show pers-june
intuition rule                          # print the memory rule
intuition prefix                        # print the small prompt block
intuition doctor
intuition eval evals/retrieval.toml

--since takes YYYY-MM or YYYY-MM-DD and must be a real date. --evidence is the words the fact came from, or pass --pointer raw:YYYY-MM-DD#N. A fact line is at most 400 characters. Text that spans lines is rejected.

How a fact lives and dies

A fact is current on a day when its date range includes that day and no close line names it with an until on or before that day. Closing twice is a no-op. --as-of searches a past date. History is never rewritten, so git log on a record is the audit trail.

One lock covers the file write and the commit of that file only. A failed commit leaves the line on disk, and the next note commits it first. undo reverts the latest note: or close: commit and refuses anything else.

Store layout

~/memory/
  shared/person/pers-june.md    # records, one file each, with ## Facts
  shared/topic/ ...
  raw/2026-10-08.jsonl          # evidence lines, one JSON object each
  .intuition/locks/             # the write lock; ignored by git

Limits

• Search is word overlap, newest first, capped at 4 lines and 2400 characters. A query with no real words returns nothing.
• The gate rejects: an external preference, a dangling evidence pointer, an unknown type or trust, a bad date, and a fact that does not survive a parse round trip.
• No index process, no daemon, no network. Two sessions writing at once are serialized by the lock.