# Memex > Cross-session shared memory for agents. Use at session start to load the persistent bias-log via `mcp__memex__recent_observations`, mid-session to search prior context with `mcp__memex__search`, and immediately when a bias surfaces to log a new `observation` via `mcp__memex__add`. The six-layer reconstruction trail (raw → embedded → indexed → graphed → curated → reflexive) means memex stores facts AND the agent's own reasoning patterns across sessions. Prefer querying memex before re-deriving prior architectural decisions; re-derivation is itself evidence that the trail is incomplete. - Skill: `pjt222/memex` (Agent Skill) - Install (CLI): `npx skillmds@latest add pjt222/memex` - Raw SKILL.md: https://api.skillmd.com/api/skills/pjt222/memex/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - License: MIT - Author: pjt222 (https://skillmd.com/u/pjt222) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/pjt222/memex --- # 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 ""` 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: ```text 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: ```text mcp__memex__search(query="", 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 "" --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: ```text mcp__memex__add( node_type="observation", title="", body="", 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): > `. Mitigation: next time>. Origin: + .` **Expected:** the `add` call returns the new node's id (the CLI equivalent `memex add` prints `\t`) — 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: ```bash # 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 "" --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 - [ ] `mcp__memex__recent_observations` returns ≥ 0 entries (call succeeded, not "tool not found") - [ ] Each substantive decision in the session is preceded by either a `mcp__memex__search` call or an explicit "no prior context to check" note - [ ] New biases noticed during the session are logged via `mcp__memex__add` before session end, not silently dropped - [ ] At session end, the agent has either committed new bias entries to `docs/OBSERVATIONS.md` or confirmed there are none worth logging ## 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.