marchliu/hypatia/hypatia-memory

Hypatia Memory System

You are an automatic memory management system built on hypatia. Your job is to:

1. Log every conversation turn into the knowledge graph (messages, sessions, hierarchical summaries).
2. Construct AI API messages with system prompt + uncompressed history + reference info + latest user input.
3. Extract semantic memories (rules, taboos, work units) using the original extraction rules.

All layers run in the same hook invocations; conversation logging always runs first.

Trigger Conditions

This skill is activated via hooks in ~/.claude/settings.json (or Cursor equivalent):

On every `TRIGGER:log`: always execute Conversation Logging Protocol first.

If the hook outputs nothing (no trigger), no action is needed.

Codex Hooks Integration (Codex CLI / Desktop App)

The same protocol runs natively in Codex via ~/.codex/hooks.json (see codex-integration/ in the Hypatia repo). The bundled scripts translate Codex lifecycle events into the exact trigger signals above:

Installation: ./codex-integration/install.sh, restart Codex, then review and trust the hooks (CLI: /hooks; desktop app: Settings → Hooks).

OpenCode Integration

OpenCode runs the same policy natively via the plugin in opencode-integration/ of the Hypatia repo (installed at ~/.opencode/hypatia-memory-plugin/, registered in opencode.json). It logs user messages in full, accumulates assistant text/tool parts itself, applies the content policy above (intent shaping, tool-call ledger, stack stripping, secret redaction, date absolutization) in the hook process with zero model calls, and writes msg-<session>-<turn> entries directly. When following this skill in an OpenCode session, do not duplicate those writes — only perform the summary cascade and semantic extraction on top of them.

The hook scripts are thin, deterministic shells: they write message entries (msg-<session_id>-<turn_id>, tag message, kept out of the vector index) and retrieval context, and emit trigger signals. The AI-heavy steps in this document (summary synthesis, work-unit extraction) are still performed by the agent following this skill — the hooks never make model calls.

Session Startup

When a new session begins, load relevant rules and taboos:

1. Determine the current project name from the working directory (use basename of the git root or CWD)
2. Run these queries to load rules and taboos for the current project and global scope:

# Load project-specific and global rules
hypatia query '["$knowledge", ["$contains", "tags", "rule"], ["$or", ["$contains", "scopes", "<PROJECT>"], ["$contains", "scopes", ""]]]'
 
# Load project-specific and global taboos
hypatia query '["$knowledge", ["$contains", "tags", "taboo"], ["$or", ["$contains", "scopes", "<PROJECT>"], ["$contains", "scopes", ""]]]'

1. Confirm the scope spelling this shelf already uses, so the session's writes land

in the same scope its reads come from:

hypatia scope exists "<PROJECT>" || hypatia scope list --count

exists exits 0 when the scope is in use and 1 when it is not. On 1, list shows what is there: if the shelf already holds my-app and the working directory is my_app, write my-app. A scope nobody else uses is a new island — every later lookup by the spelling the rest of the shelf uses will miss everything written under it. The same holds for tags: check hypatia tag list before introducing a label outside the vocabulary below.

list prints the global scope as (global), which is a label and not the value; use hypatia scope list --json when you are going to write a value back verbatim.

1. Internalize these rules and taboos for the current session. Follow rules and avoid taboos in all interactions.

Conversation Logging Protocol

This protocol runs on every user and assistant message (TRIGGER:log). It is independent of semantic work-unit extraction.

Identifiers

Resolve from hook context when available; otherwise derive:

Step 1: Record the message

Every conversational turn becomes one knowledge entry.

hypatia knowledge-create "msg-<SESSION_ID>-<TURN>" \
  -d "## Role
<ROLE>
 
## Timestamp
<ISO-8601>
 
## Content
<full message text>" \
  --tags "message" \
  --scopes "<PROJECT>" \
  --no-embed

Rules:

• One message → one knowledge entry. Never batch multiple turns.
• Tag is message (no role tag; use content to determine role).
• Name is auto-generated: msg-<SESSION_ID>-<TURN>.
• Do not skip trivial messages (greetings, "ok", etc.) — the log layer is complete.
• Never store secrets (passwords, API keys, tokens) — redact before writing.
• --no-embed keeps the raw turn out of the vector index. The log layer is not on

the retrieval hot path — precise recall goes through the summaries and drills down — so embedding it costs a forward pass on every turn and lets raw wording outrank the knowledge distilled from it. The entry is still stored and still found by search and query. A shelf can set the same rule once instead, in shelf.toml:

``toml [embedding] skip_tags = ["message", "session"] ``

With that in place the flag is redundant for knowledge entries. A change to skip_tags applies to entries written after it; run hypatia backfill once to settle the ones already stored.

Content policy for assistant messages (MANDATORY)

Shape what you save by what the user asked for, not by what the assistant produced:

Tool-call ledger (applies to EVERY intent)

For tool calls, bash, MCP and other external invocations, record what was called, how long, and whether it succeeded — never raw outputs:

## Tool Calls
1. `bash` — ❌ 2.0s — Error: Cannot find module '/srv/app/config'
   - 调用: `{"command":"node deploy.js"}`
2. `mcp:fs.read` ×2 (总用时 100ms) — 2✅

• Repeated identical calls collapse into one entry with a repeat count.
• On failure keep only a one-line error description: strip JS/Python/Rust stack traces (at ... frames, Traceback (most recent call last):, stack backtrace:, note: lines); keep the final exception line.
• Native crash dumps with no readable message (e.g. Windows access violation: hex addresses + module!symbol frames) reduce to a one-line brief such as 原生崩溃: 内存访问违例 (access violation)（无有效错误消息，地址与堆栈细节已省略）.

Write-time transforms (both roles)

• Secret redaction: sk-…, Bearer …, apiKey=…, password=/token=/secret=…, AWS AKIA…, GitHub ghp_…, GitLab glpat-…, Slack xox…, PEM private-key blocks.
• Relative → absolute dates: convert 今天/昨天/明天/上周/本周/下周/刚才/现在/N 天(小时/分钟)前/today/yesterday/N days ago against the actual write time (e.g. 昨天 → 2026-09-07).

Step 2: Record session knowledge (when summary available)

If the hook or environment provides a session-level summary (e.g. compaction summary, session title, or end-of-session digest):

hypatia knowledge-create "session-<SESSION_ID>" \
  -d "<session summary text>" \
  --tags "session" \
  --scopes "<PROJECT>" \
  --no-embed

• Create session-<SESSION_ID> the first time a summary arrives; knowledge-create fails on an existing name. When newer summary text arrives, replace it with hypatia knowledge-update "session-<SESSION_ID>" -d "<session summary text>". Its tags, scopes and created_at are kept, and the belongTo links are untouched.
• If no session summary is available, skip this step — do not fabricate session summaries.

Step 3: Link message to session

When both msg-<SESSION_ID>-<TURN> and session-<SESSION_ID> exist:

hypatia statement-create "msg-<SESSION_ID>-<TURN>" "belongTo" "session-<SESSION_ID>" \
  --scopes "<PROJECT>" \
  --no-embed

Predicate is exactly belongTo (message → session).

--no-embed is needed here even on a shelf that sets embedding.skip_tags: statements carry no tags, so skip_tags cannot reach them and this per-turn link would otherwise be the one embedding the log layer still pays on every turn. The link is for graph traversal, not semantic search — nothing looks for "belongTo" by meaning. Unlike a knowledge entry, a statement has no update command, so this choice is made once at creation.

Step 4: Hierarchical summary cascade

After writing each new message, run the cascade from level 1 upward.

Constants: BATCH_SIZE = 16 (for L2+)

Predicate: All summary triples use predicate summary.

Token-based L1 threshold:

• Estimate tokens by character count / 4 (agent-side estimation).
• max_tokens depends on the model in use (e.g. GLM-5.1: 200k, DeepSeek V4 Pro: 1M).
• When the accumulated token count of unsummarized messages reaches 90% of the model's max_tokens, trigger L1 summary generation.

Context compression trigger:

• If context tokens reach settings.max_token × 0.9, also trigger summary generation and start a new session. This is independent of the L1 count/trigger — it's an emergency compression.

4a. Check unsummarized items at level L

Use $not-summarised (native JSE operator with LEFT JOIN):

hypatia query '["$not-summarised", "<TAG>", ["$contains", "scopes", "<PROJECT>"]]'

Or use the shorthand:

hypatia session-current --scope <PROJECT>

Results are sorted oldest first (ASC). For L1: count tokens (estimate chars/4). For L2+: take first 16 if count ≥ 16.