About
This skill logs bias or reflection observations to a memex store during a session. It triggers when you detect reasoning patterns like anchoring or need to persist insights from meditation. It primarily adds entries via `memex add` for queryability and secondarily appends to an OBSERVATIONS.md file.
Quick Install
Claude Code
Recommendednpx skills add pjt222/agent-almanac -a claude-code/plugin add https://github.com/pjt222/agent-almanacgit clone https://github.com/pjt222/agent-almanac.git ~/.claude/skills/memex-observeCopy and paste this command in Claude Code to install this skill
Documentation
Log a Memex Observation
Capture a bias-log / vipassana reflection — a pattern you noticed in your own
reasoning — into the canonical memex store while the context is still fresh.
This is the focused wrapper for the umbrella memex skill's "log an
observation" step: use it when the task is purely record this bias, not the
full session-start-to-close flow.
When to Use
- Immediately when a bias surfaces in your reasoning. Anchoring on an early decision, confirming a hypothesis instead of testing it, trusting a summary over source truth — log it the moment you catch it, not at session end where it is reconstructed from memory and loses specificity.
- When a pace tell or verification gap appears. Rushing past a confusing measurement, re-deriving something that already exists, skipping a check you know matters.
- At session close, after
meditateorobserve. Either reflection skill can surface a new pattern worth persisting; this skill deposits it. - When backfilling. Several observations accumulated in notes and need to land in the canonical store in one pass — use the secondary path.
Inputs
- Required: The memex repo checked out (a checkout of
github.com/pjt222/memex) with cwd = repo root. Theextractstep defaults its registry path toextractors/sources.ymlrelative to cwd. - Required:
$MEMEX_STORE_PATHset (everymemexcommand hard-errors without it). - Required for the db write:
$MEMEX_PG_URLset, and a running Postgres. Pass--no-dbto skip the db and write only the markdown store. - Required: a built binary —
cargo build --release -p memex-cliproduces./target/release/memex(not onPATHby default). - Optional:
$MEMEX_EMBED_PROVIDER=voyage+$VOYAGE_API_KEYif you intend to query the observation back via semantic/hybrid search afterward.
Procedure
Step 1: Shape the observation body
Read the authoritative "Two paths to add an observation" block in
docs/OBSERVATIONS.md (lines 10-21) and the existing entries below it for
voice. An observation has three parts: what the bias was, what to do next
time, and where it came from. The shape (example, current as of v0.4.0;
docs/OBSERVATIONS.md is the source of truth and is parsed by
crates/memex-extract/src/meditate_vipassana.rs):
<Description of the bias as it surfaced>. Mitigation: <what to do next time>. Origin: <date> + <context>.
Expected: A one-to-few-sentence body ending in a Mitigation: clause and
an Origin: clause. A short bias name (the --title) distinct from the body.
On failure: If you cannot name the mitigation, the observation is not yet ripe — keep observing. A bias with no "what to do next time" is a complaint, not a logged pattern.
Step 2 (Path A, primary): Add via the CLI over stdin
The body is read from stdin and --title is required (there is no
default). Pipe the body in:
echo "<body>. Mitigation: <...>. Origin: <date> + <context>." \
| ./target/release/memex add \
--type observation \
--title "<short bias name>" \
--tags bias-log,vipassana
Add --no-db to write only the markdown store (skips the $MEMEX_PG_URL
requirement). A concrete example:
echo "Anchored on the first store layout and never re-opened it after scope grew. Mitigation: schedule a re-check beat at the next milestone boundary. Origin: 2026-06-17 + M5 watcher scoping." \
| ./target/release/memex add \
--type observation \
--title "Anchoring on initial store layout" \
--tags bias-log,vipassana
Expected: The command exits 0 and prints the new node's UUID and store
path (tab-separated). The entry now exists in the store (and the db, unless
--no-db).
On failure: "$MEMEX_STORE_PATH not set" → export it. A db connection
error → export $MEMEX_PG_URL and confirm Postgres is up, or re-run with
--no-db. "--title is required" → supply --title; it has no default.
Empty/hung on stdin → you did not pipe a body; memex add blocks waiting for
stdin.
Step 3 (Path A, primary): Make it queryable
The add deposits the node, but the vipassana index is rebuilt by the
extractor. Run it from the repo root (the command is cwd-sensitive — the
--registry default is extractors/sources.yml relative to cwd):
./target/release/memex extract meditate-vipassana --registry extractors/sources.yml
meditate-vipassana is the extractor name; extract matches registry
entries on their extractor: field, so this re-runs the observations
source. Use --dry-run first to preview without writing.
Expected: Exits 0; prints extraction stats (nodes/edges touched). The
observation is now queryable, e.g.
./target/release/memex query "bias-log" --node-type observation --mode semantic.
On failure: "no registry entries match extractor meditate-vipassana" →
you are not at the repo root, or passed the wrong --registry; cd to the
repo root and pass --registry extractors/sources.yml explicitly. Semantic
query returns nothing → embeddings are not configured; set
$MEMEX_EMBED_PROVIDER=voyage + $VOYAGE_API_KEY, or query with
--mode keyword (but note --node-type is silently ignored in keyword mode).
Step 4 (Path B, secondary): Append a numbered bullet
For batch backfill, or when you prefer editing the canonical markdown
directly, append to the ## Vipassana observations block in
docs/OBSERVATIONS.md. Numbering is monotonic: read the current maximum
entry number (9 at v0.4.0) and use max + 1. The bullet shape:
N. **Title.** body. Mitigation: <what to do next time>. Origin: <date> + <context>.
Then run the extractor (Step 3) to index the new bullet into the store and db.
Expected: A new entry numbered one above the prior maximum, ending in
Mitigation: and Origin: clauses, indexed by the Step 3 extract.
On failure: Extractor skips your bullet → the parser only accepts entries
under ## Vipassana observations, ## Bias log, ## Bias-log observations,
or ## Vipassana (case-insensitive), in the N. **Title.** ... shape;
confirm the heading and the bold-title marker. Duplicate or non-monotonic
number → renumber so the sequence has no gaps or repeats.
Validation
- The body ends with a
Mitigation:clause and anOrigin:clause - Path A:
memex addexited 0 and printed a UUID;--titlewas supplied - Path A:
memex extract meditate-vipassanaexited 0 after the add - Path B: the new bullet number is exactly the prior maximum + 1, with no gaps or repeats, under a parser-recognized heading
- The observation describes the agent's own reasoning pattern, not a
reusable architectural fact (that belongs in a
conceptnode) - The observation is logged before session end, not silently dropped
Common Pitfalls
- Forgetting stdin.
memex addreads the body from stdin and blocks if nothing is piped. Alwaysecho "..." | memex add ...(or redirect a file); there is no--bodyflag. - Omitting
--title. It is required and has no default. The short bias name is the title; the full context is the piped body. - Running
extractfrom the wrong directory.--registrydefaults toextractors/sources.ymlrelative to cwd. Run from the repo root or pass--registryexplicitly, or the extractor finds no entries. - Confusing this with
memex init.memex initis CLI store/db setup — it is not part of logging an observation and not thememex-initsession ritual. Never runmemex inithere. - Logging at session end only. Biases caught at close are reconstructed from memory and lose specificity. Log them the moment they surface.
- Logging a concept as an observation. Observations are about your
reasoning patterns. A reusable fact about the system is a
conceptnode. - Expecting
--node-typeto filter keyword queries. It is silently ignored inkeywordmode (tracked tech-debt); onlysemantic/hybridhonor it, and those need embeddings configured.
Related Skills
memex— the umbrella skill; this is the focused wrapper for its "log an observation" step. Use the umbrella for the full session flow.memex-wrap— session-close counterpart; flushes mid-session observations to the canonical store and verifies the trail before handoff.meditate— full reflective close; its vipassana output is exactly what this skill persists.observe— sustained neutral pattern recognition; when it surfaces a recurring reasoning pattern, log it here.
GitHub Repository
Frequently asked questions
What is the memex-observe skill?
memex-observe is a Claude Skill by pjt222. Skills package instructions and resources that Claude loads on demand, so Claude can perform memex-observe-related tasks without extra prompting.
How do I install memex-observe?
Use the install commands on this page: add memex-observe to Claude Code as a plugin, or clone its repository into your skills directory, then restart Claude so it picks up the skill.
What category does memex-observe belong to?
memex-observe is in the Design category, tagged design.
Is memex-observe free to use?
Yes. memex-observe is listed on AIMCP and free to install. It runs inside Claude, so no separate service account is required to use the skill itself.
Related Skills
Use the executing-plans skill when you have a complete implementation plan to execute in controlled batches with review checkpoints. It loads and critically reviews the plan, then executes tasks in small batches (default 3 tasks) while reporting progress between each batch for architect review. This ensures systematic implementation with built-in quality control checkpoints.
This skill dispatches a code-reviewer subagent to analyze code changes against requirements before proceeding. It should be used after completing tasks, implementing major features, or before merging to main. The review helps catch issues early by comparing the current implementation with the original plan.
This skill provides a comprehensive guide for developers to connect MCP servers to Claude Code using HTTP, stdio, or SSE transports. It covers installation, configuration, authentication, and security for integrating external services like GitHub, Notion, and custom APIs. Use it when setting up MCP integrations, configuring external tools, or working with Claude's Model Context Protocol.
This skill helps developers choose between Claude Code Web and CLI interfaces based on task analysis, then enables seamless session teleportation between these environments. It optimizes workflow by managing session state and context when switching between web, CLI, or mobile. Use it for complex projects requiring different tools at various stages.