Memex
Agent-native shared memory. Postgres + pgvector index over a canonical
markdown store, exposed over MCP. Lives at https://github.com/pjt222/memex.
When to Use
- At session start, always. Call
mcp__memex__recent_observations
before substantive work. Loads the bias-log from prior sessions.
- Mid-session, when about to make a non-trivial decision. Call
mcp__memex__search "<topic>" to check whether the project has
converged on this before.
- Immediately when a bias surfaces in your own reasoning. Log an
observation via mcp__memex__add while the context is fresh. Do
NOT wait for session end.
- When you catch yourself re-deriving something. Re-derivation
IS the signal that the trail is incomplete; capture the gap as an
observation and link to whatever you re-derived.
Inputs
- Required: A registered
memex MCP server in the active harness.
Verify with claude mcp list | grep memex (Claude Code) or the
equivalent in your harness.
- Required:
$MEMEX_PG_URL and $MEMEX_STORE_PATH in the
server's environment.
- Optional:
$MEMEX_EMBED_PROVIDER=voyage + $VOYAGE_API_KEY
for semantic / hybrid search. Without these, mode=keyword still
works.
Procedure
Step 1: Load the bias-log
Before any substantive work in a fresh session, call:
mcp__memex__recent_observations(limit=20)
Read every returned entry. Each one is a pattern the agent (you, or a
prior instance) noticed in its own reasoning. Recurring patterns are
the most valuable; transient ones are still cheap to skim.
Expected: 5–30 observations covering biases (availability,
confirmation, anchoring), pace tells (rushing past confusing
measurements), and verification gaps (trusting summaries over source
truth).
On failure: If the call fails with "tool not found", the MCP
server isn't registered; run adapters/claude-code/install.sh (or
the per-harness equivalent) from the memex repo first.
Step 2: Search before deriving
When a non-trivial decision approaches (architectural, naming,
algorithmic), search first:
mcp__memex__search(query="<topic>", mode="hybrid", k=10)
For exact-wording lookups use mode=keyword. For purely conceptual
queries (topic unlikely to share tokens with indexed text) use
mode=semantic. Optional node_type filter restricts to one type
(e.g. observation).
Expected: 0–10 hits. Even 0 hits is useful — it tells you the
trail doesn't cover this decision, so your present reasoning becomes
the canonical record.
On failure: If search errors (server down or db unreachable),
fall back to the CLI substitute memex query "<topic>" --node-type observation (defaults to hybrid, which honors the type filter via
its semantic leg). If it returns 0 hits on a topic that clearly should
have coverage, treat the gap as a signal and proceed to Step 4.
Step 3: Log observations mid-session
When you notice a bias in your own reasoning:
mcp__memex__add(
node_type="observation",
title="<short bias name>",
body="<context, mitigation, origin date>",
tags=["bias-log", "vipassana"]
)
Body convention (mirroring docs/OBSERVATIONS.md in the memex repo;
treat that file as the source of truth — it is read by an extractor):
<Description of the bias as it surfaced>. Mitigation: <what to do next time>. Origin: <date> + <context>.
Expected: the add call returns the new node's id (the CLI
equivalent memex add prints <uuid>\t<store-path>) — confirmation
the observation is in the canonical store.
On failure: rmcp dispatches tool calls concurrently — if add
races a dependent call (add → link), await its response first. If
the db is unreachable the write is lost; re-issue once the server is
back, or fall back to appending the entry to docs/OBSERVATIONS.md by
hand (Step 4).
Step 4: Surface unknowns
If recent_observations is empty (fresh memex install), or search
returns nothing on a topic that clearly should have coverage, that's a
documentary trail gap. Close it by appending to the canonical markdown
and re-extracting, or by depositing directly via the MCP tool:
# Backfill path (run from the memex repo root):
$EDITOR docs/OBSERVATIONS.md # append under "## Vipassana observations"
memex extract meditate-vipassana --registry extractors/sources.yml
Or use mcp__memex__add (Step 3) during the session to deposit the
entry into the canonical store on the spot, without touching the file.
Expected: after extract, the new observation is queryable —
memex query "<its topic>" --node-type observation returns it (the
observation-node count grows by one).
On failure: extract is cwd-sensitive — run it from the memex
repo root or pass --registry. If it reports "no new sources", the
content hash already matched; confirm the append actually landed in
docs/OBSERVATIONS.md.
Validation
Common Pitfalls
- Skipping the session-start call. The single highest-value
use of memex. Skipping it is the strongest tell that the agent is
treating each session as starting from scratch.
- Logging at session end only. Biases caught at session end are
reconstructed from memory and lose specificity. Log them
immediately when they surface.
- Logging an observation that's actually a concept. Bias-log
entries are about the agent's own reasoning patterns. Reusable
architectural facts belong in
concept nodes.
- Trusting search results over reading them. A title that
matches your query isn't proof the body answers it. Fetch the
full body with
mcp__memex__get when in doubt.
- Pipelining dependent MCP calls in one session. rmcp dispatches
tool calls concurrently. If a later call depends on a write from
an earlier call (add → link → neighbors), await each response
before issuing the next.
Related Skills
memex-init — session-start ritual that wires memex into a fresh
session; run it before this umbrella's Step 1 to register the
server and load the bias-log.memex-observe — the focused wrapper for Step 3; use it when the
task is purely "log a bias I just noticed" rather than the full
umbrella flow.memex-wrap — session-close counterpart; confirms observations are
logged (deferring the actual write to memex-observe) and writes the
continuation trail this skill reads next session.memex-verify — pre-commit gate for the memex repo itself; run it
before committing changes to memex (cargo fmt / clippy / test).breathe — pair with memex at session boundaries: breathe to
release prior-session residue, then recent_observations to load
the next-session priors.meditate — full reflective close; outputs new observations
worth logging via mcp__memex__add.read-continue-here — complementary; loads project-state
pickup doc. Memex loads cross-project bias-log; CONTINUE_HERE
loads project-specific milestone state.