From agent-almanac
Cross-session shared memory for AI agents using Postgres+pgvector. Loads bias-log at session start, searches prior decisions mid-session, and logs reasoning patterns via MCP.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agent-almanac:memexThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Agent-native shared memory. Postgres + pgvector index over a canonical
Agent-native shared memory. Postgres + pgvector index over a canonical markdown store, exposed over MCP. Lives at https://github.com/pjt222/memex.
mcp__memex__recent_observations
before substantive work. Loads the bias-log from prior sessions.mcp__memex__search "<topic>" to check whether the project has
converged on this before.observation via mcp__memex__add while the context is fresh. Do
NOT wait for session end.memex MCP server in the active harness.
Verify with claude mcp list | grep memex (Claude Code) or the
equivalent in your harness.$MEMEX_PG_URL and $MEMEX_STORE_PATH in the
server's environment.$MEMEX_EMBED_PROVIDER=voyage + $VOYAGE_API_KEY
for semantic / hybrid search. Without these, mode=keyword still
works.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.
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.
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).
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.
mcp__memex__recent_observations returns ≥ 0 entries (call
succeeded, not "tool not found")mcp__memex__search call or an explicit "no prior context
to check" notemcp__memex__add before session end, not silently droppeddocs/OBSERVATIONS.md or confirmed there are none worth
loggingconcept nodes.mcp__memex__get when in doubt.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.npx claudepluginhub pjt222/agent-almanacLogs bias-log / vipassana observations to a memex store when reasoning patterns surface. Captures anchoring, confirmation bias, pace tells, and verification gaps mid-session or at close.
Guides agents to deliberately search or skip memory using dejavu MCP tools, with query strategies and metadata filters for decisions, user preferences, conventions, and anti-patterns.
Self-hosted semantic memory for AI agents via MCP. Saves worklogs, decisions, and notes retrievable by meaning across sessions using Postgres + pgvector with auto-tagging.