This server provides an evidence-based personal memory system for AI agents: it captures user words verbatim, derives structured knowledge, and enforces a hard validation gate before answering.
Preflight every user turn to detect personal content and persist a turn receipt.
Capture the full user message verbatim with timestamps/session metadata, and refuse non-personal or unprepared turns.
Read memory via survey → probe/deep retrieval, gated on the current turn's capture.
Add derived records (events, entities, decisions, preferences, states, etc.) with source/verbatim refs, salience, confidence, sensitivity, and date precision.
Close each capture with a derivation-loop finalization: require linked records or an explicit "nothing new" reason.
Check derivation status for pending captures, orphans, and link drift.
Register scheduled follow-ups with context and due rules for proactive check-ins.
Record candidate causal hypotheses (with supports/contradicts/alternatives/scope) as candidates, not facts.
Validate archive structure and distinguish clean/warnings/failed; strict mode requires all captures finalized.
Log feedback (helpful/missed/corrected) tied to memory IDs for future improvement.
Run session_check as a mandatory pre-answer gate ensuring turn receipt, capture closure, structure, and v2 integrity.
Allows backing up the memory archive to any rclone remote, enabling mirror-to-second-location backups with integrity verification.
Verbatim-first · Evidence-chain · Anti-fabrication · Local-first · One folder, zero dependencies
Two skill languages: the repo ships
SKILL.md(English) andSKILL.zh-CN.md(中文) — two brains, one shared bilingual engine. Install either by renaming it toSKILL.mdin your skills folder. 中文用户可直接用SKILL.zh-CN.md，配合中文档案效果最佳。
agent-memory mcp claude codex skills local-first personal-knowledge
Typical agent memory has a dirty secret: the model summarizes first and stores the summary. Your words get paraphrased, compressed, and blended with the model's own interpretations on day one. Six months later, "you" are a stack of lossy summaries — and when the model gets you wrong, you can't even audit why, because the original evidence is gone.
Worse, failures are silent: a corrupted write reports success, an invented date looks plausible, the model's guess about why you are the way you are quietly hardens into "fact".
Personal Understanding flips the pipeline:
Save the exact words first. Derive everything else from them. Prove every path.
Every personal message is captured verbatim and immutably (SHA-256 hashed, timestamped, session-tagged) before anything else happens. Structured understanding — timeline, entities, context cards, causal hypotheses — is then built on top of the evidence, with every derived fact linking back to the quote it came from. When the agent misremembers you, you audit it. When it doesn't know, it says so.
Related MCP server: ForkMind
Typical memory tools | Personal Understanding | |
What gets stored first | the model's summary | your exact words — immutable, hashed |
Derived facts traceable to source | rarely | ✓ every record links back to its verbatim |
Model guesses marked as guesses | no | ✓ hypothesis layer, |
Old lossy summaries | silently reused | ✓ flagged as summary debt — retrieval discloses "this part comes from an old summary" |
Says "saved" when the save failed | happens | ✗ impossible — capture is read back; a hard gate ( |
Invented dates, merged people, fake causal edges | possible | ✗ forbidden by written policy and enforced by validators |
Runtime | server + vector DB + embeddings | one folder, Python stdlib only |
Where your data lives | often their cloud | your machine. Full stop. |
Newer agents ship with "memory" now — if that's enough for you, use it. This project exists for the people who hit its walls:
Built-in agent memory | Personal Understanding | |
Data ownership | locked in the vendor's account, rarely exportable, gone when you switch tools | a plain-text folder on your machine — read it, grep it, back it up, move it |
Portability | memory only works inside that product | one archive, any MCP client — Claude, Codex, ZCode, VS Code, whatever comes next |
Auditability | black box — you can't see what got stored, or why it answered that way | every derived fact links back to the exact quote; ask "where does that come from?" and get shown the source |
Control | an on/off switch | you own the policy — capture gates, salience, sensitivity labels, follow-up rules |
Retrieval | fuzzy summary recall | three-layer recall that bottoms out in your original words |
Privacy | your personal history on their servers | local only — no telemetry, no cloud calls |
Vendor memory optimizes for a smoother conversation inside their product. This project optimizes for a memory you own, that moves with you across tools, and that can prove where every fact came from. Different products — vendor memory getting better doesn't make this one redundant.
Without Personal Understanding — a typical memory implementation:
You: I finally played my first full song on guitar today. Three weeks until I perform it at my cousin's wedding — honestly less nervous than before. AI: That's awesome, congrats! 🎸 Keep it up!
What got stored:
"user played guitar, feeling positive."A lossy summary. No source, no date, no people, no way to check it. Next month it's gone — or worse, silently paraphrased into something you never said.
With Personal Understanding — the same message:
You: I finally played my first full song on guitar today. Three weeks until I perform it at my cousin's wedding — honestly less nervous than before. AI: (first: captures your complete message verbatim — SHA-256-hashed, timestamped, session-tagged — before anything else) (then: derives and links —
event"first full song on guitar" · saliencesupporting· linked toSaraand the wedding goal · updates your current state: performance anxiety ↓) AI: First full song is a real milestone. Last time, performing at the wedding made you nervous — how does it feel now that it's three weeks out?Every claim traces back to your exact words. Ask "where does that come from?" and the agent shows you the original quote — not a paraphrase of a paraphrase. And when it's the wedding week, the archive checks in by itself.
🗣️ Verbatim-first capture — the complete message, word for word, before any summarizing, splitting, or interpreting. Corrections add new captures; nothing is ever silently overwritten.
🔁 Derivation closure — a successful capture is not a finished update. Every capture must be split into records, linked, and closed — or explicitly closed as "nothing new" with a stated reason. Orphans can't slip through.
🧠 Human-like three-layer recall — survey (a compact routing map) → probe (fan out along entities, context cards, and time neighbors) → deep (verify the exact quote). No vector dumps, no keyword-only search.
📻 Cold recall ladder — for "I forget, we talked about something like this…" moments: probe from any hint, walk time neighbors, then browse a time window like flipping through an old photo album.
🕸️ Entities + context cards — people, schools, places, objects, works, games, concepts, environments — plus cross-entity cards ("school × football") so shared stories are reachable from any side. Vague pronouns are kept as unresolved_referent, never fabricated into fake people.
🔬 Causal hypothesis layer — "why am I like this?" gets a structured answer: claim, mechanism, supports, counterexamples, competing explanations, scope, confidence — always candidate, never presented as fact.
⏰ Proactive follow-ups — "let's see in a few days" becomes a tracked loop. When it's due, the agent checks back with the original context, not a context-free nag.
🧭 Guided starters — you don't have to know what to say. The skill reads its own gaps (empty domains, open loops, stale current state) and offers one warm, concrete question at a time (python scripts/conversation_starters.py).
🚦 Hard gates, not vibes — three-state validation (clean / warnings / failed), atomic writes everywhere, session_check as a non-zero-exit gate before any "the archive is updated" claim.
📉 Summary debt accounting — legacy material that lost its source is labeled, counted, and disclosed in retrieval. It can never impersonate verbatim.
📊 Audit dashboard — a local, read-only panel: real counts, validation state, and the full chain from any event back to the original words. The point is that you can check the skill follows its own rules.
🔌 Drop-in for your client — an idempotent installer auto-detects and registers a local MCP server across Claude clients, Codex, VS Code / Cursor / Windsurf / Cline / Trae, ZCode, and generic .agents configs.
💾 Backups with integrity — SHA-256-manifested snapshots, mirror-to-second-location support (any rclone remote), and a quarterly salience review that gracefully demotes stale imported weights instead of letting them fossilize.
flowchart LR
A["user message"] --> B{"turn preflight<br/>(router)"}
B -->|"personal content"| C["immutable verbatim capture<br/>+ SHA-256 · session · source"]
C --> D["derivation ledger<br/>(pending)"]
D --> E["derive: events · entities<br/>context cards · hypotheses<br/>follow-ups"]
E --> F["finalize:<br/>derived / nothing-new"]
B --> G["survey → probe → deep<br/>progressive retrieval"]
G --> H["deep = verbatim only<br/>(summary debt disclosed)"]
F --> I["session_check<br/>hard gate · must exit 0"]
I --> J["answer"]
J --> K["feedback loop<br/>helpful / missed / corrected"]
K -.->|quarterly| L["salience review<br/>+ deep semantic review"]On disk it's plain files you can read, grep, and back up: sources/conversation/ (immutable verbatim + hashes) and memory/v2/ (fragments, timeline, entities, contexts, follow-ups, hypotheses, decision traces) — with legacy records kept as a compatibility layer and honestly marked summary_only.
# 1. clone into your client's skills directory
git clone https://github.com/caix84476-netizen/personal-understanding.git \
~/.claude/skills/personal-understanding # or ~/.codex/skills/ , or your client's equivalent
# 2. bootstrap the archive skeleton (directories + generic domain branches; idempotent)
python scripts/init_archive.py
# 3. register the local MCP server (auto-detects clients; idempotent)
python scripts/install_mcp.py --auto # Windows: just double-click register-mcp.cmd
# 4. restart your client session — the personal_* tools go live
# 5. open the audit dashboard any time
python scripts/open_dashboard.py # Windows: double-click open-dashboard.cmdRequirements: Python 3.10+ · stdlib only, zero pip installs · Windows / macOS / Linux.
Prefer pip? The MCP server + installer are also on PyPI: pip install personal-understanding, then personal-understanding-install to register the local MCP server. The pip package ships the Python side only — for the full skill brain (SKILL.md + dashboard), use the clone steps above. As of 2.2.1 the wheel is no longer a stale snapshot — all 37 packaged files are byte-identical to scripts/ in the source tree. One caveat remains: personal-understanding-install registers the server but does not bootstrap an archive root, so start from scratch with python -m personal_understanding.init_archive. The clone steps above remain the recommended path for the full skill.
Then just talk normally: "I've been feeling…", "remember that…", "why do I keep…" — the skill's description triggers on personal content, captures your words, and takes over from there. Ask "what do you remember about…", or "where does that come from?" and follow the evidence chain.
Everything is processed locally, in the skill folder. No telemetry, no cloud calls, no embeddings shipped to third parties.
The shipped .gitignore blocks memory/, sources/, and backups/ — so you can version-control your skill folder and never commit your private archive by accident.
Sensitivity labels (private / highly-private) control relevance, not secrecy-from-you: unrelated questions never leak unrelated private material.
These are written policy, enforced by validators — not aspirations:
Verbatim fidelity first — no summary ever poses as the user's words; summary_only is marked as such forever.
No fabricated certainty — uncertain dates stay uncertain; vague pronouns don't become people; single events never become causes.
Newer words outrank older archives — corrections build supersedes / contradicts chains; nothing is silently erased.
One salience axis — pivotal / key / supporting / passing on a single 0–3 scale; imported weights admit they're heuristics.
Silence is not feedback — only explicit corrections and confirmations, with quotable evidence, feed the feedback loop.
Structure clean ≠ semantically correct — deep review exists precisely because validators can't catch meaning.
Not a framework thought up in one afternoon — a working archive refined through daily use and a dozen hardening rounds (see the CHANGELOG): a salience-decay bug that once shredded frontmatter is why all writes are now atomic and reviewed; survey used to load ~818 KB of legacy catalog per turn — it's a ~90 KB routing map now (~230 ms); the whole derivation-closure and hard-gate machinery exists because "trust me, I saved it" wasn't good enough for real life.
Current release: v2.3.1 — three-tier invocation (full/light/skip); schema stable (memory/v2/ v2.0.0), actively maintained. Also on PyPI.
Works with any MCP-capable client; the skill itself works in any language (English by default — it mirrors yours).
Roadmap: editable dashboard pages, richer cold-recall ranking, optional encrypted archive-at-rest.
Issues and PRs welcome — especially: new client installers for install_mcp.py, dashboard improvements, and i18n of the low-signal detector.
MIT © 2026 caix84476-netizen
If Personal Understanding saves you from re-explaining yourself to your AI for the nth time, a star ⭐ helps others find it.
记录一次依赖个人记忆的回答的效果：用了哪些记忆、用户反应说明 helpful/missed/corrected。不需要用户正式打分。
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| outcome | Yes | ||
| capture_id | No | ||
| memory_ids | No | ||
| feedback_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that feedback is informal and inferred from user reaction rather than formal scoring, and it names the outcome categories. However, it does not state whether this creates or updates a record, how identifiers should be supplied, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence that front-loads the purpose and ends with a clarifying exclusion. Every part earns its place; no redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, 0% schema coverage, no annotations, and no output schema, the description is not sufficient for correct invocation. It lacks details on feedback_id and capture_id provenance and on how the record is stored or returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning for outcome and memory_ids ('用了哪些记忆'), but it leaves the required feedback_id unexplained and does not clarify note or capture_id. An agent cannot reliably know what values to provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records the effect of an answer that relied on personal memory, listing what is recorded (used memories and user reaction) and the outcome categories. This is specific and distinguishes it from sibling tools like personal_add_record or personal_add_followup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: use after a memory-dependent answer when the user's reaction indicates helpful, missed, or corrected. It also explicitly excludes formal rating/scoring. It doesn't name alternative siblings, but the intended scenario is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
登记有上下文的待回访问题；到期后由个人理解 Skill 主动检查。
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| due_at | No | ||
| prompt | Yes | ||
| context | Yes | ||
| due_rule | No | ||
| priority | No | normal | |
| source_refs | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It does reveal that the tool registers follow-ups with context and that due items are later checked by a Personal Understanding Skill, which is useful. It does not describe mutation effects, duplicate handling, idempotency, or what happens when due_at is null, but the core persistence-and-check behavior is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. It states the action first and then the relevant follow-up behavior, making it easy for an agent to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a seven-parameter write operation with no annotations, no output schema, and no parameter descriptions, this is under-specified. The agent would still need to infer the meaning of several parameters and operational details such as return behavior and due handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for seven undocumented parameters. It only alludes to context and due behavior; id, due_rule, priority, and source_refs remain semantically unexplained. One sentence is insufficient to replace absent parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly centers on registering a pending follow-up/revisit and adds the lifecycle behavior that it will be actively checked when due. This is specific enough to differentiate its core purpose, though it does not explicitly distinguish it from personal_add_record or other personal_* write tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase '登记有上下文的待回访问题' implies the tool is for storing context-carrying follow-ups rather than immediate actions, and the due-check behavior gives a signal about when it applies. However, it provides no explicit when-to-use versus alternatives such as personal_add_record or personal_add_feedback.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
登记候选因果解释；默认 candidate，不得冒充事实。
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| claim | Yes | ||
| scope | No | ||
| supports | No | ||
| mechanism | Yes | ||
| confidence | No | low | |
| contradicts | No | ||
| source_refs | No | ||
| alternatives | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It usefully discloses that items are stored as 'candidate' by default and must not be presented as facts. However, it does not mention persistence behavior, side effects, idempotency, validation, or what happens after creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short, front-loaded, and contains no filler. Both clauses earn their place, though for a 9-parameter tool with no parameter documentation, the terseness leaves out important detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the absence of annotations and output schema, and the presence of similar sibling tools, the description is not complete enough. It omits return behavior, required parameter guidance, relationship to other add tools, and any operational constraints beyond the candidate/fact distinction.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the 9 parameters, such as id, claim, mechanism, confidence, or source_refs. It only conveys the overall object type ('candidate causal explanation'), so an agent gets little help with parameter-level semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: '登记候选因果解释' (register candidate causal explanation). It also explicitly contrasts hypotheses with facts via '不得冒充事实', which differentiates this tool from fact-recording siblings like personal_add_record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates this tool is for candidate causal explanations and should not be used for established facts. It provides a clear when-to-use context, though it does not explicitly name alternative sibling tools or spell out when to choose them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
创建派生记录。若来源是当前用户补充，必须先有 verbatim capture，并把 verbatim_refs 写入记录。
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| kind | Yes | ||
| phase | No | ||
| domain | No | ||
| aliases | No | ||
| summary | Yes | ||
| date_end | No | ||
| salience | No | ||
| capture_id | No | ||
| confidence | No | high | |
| date_basis | No | ||
| valid_from | No | ||
| entity_refs | No | ||
| record_role | No | ||
| related_ids | No | ||
| sensitivity | No | ordinary | |
| source_refs | No | ||
| verbatim_refs | No | ||
| date_precision | No | ||
| last_confirmed | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the prerequisite about verbatim captures, but it does not describe the creation semantics, required effects, permission needs, reversibility, or what happens when the source is not a user supplement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence with no filler, and the key prerequisite is placed in the second clause. It is compact, though it may be too terse given the tool's 20 parameters and no annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A 20-parameter creation tool with no annotations, no output schema, and no sibling differentiation needs far more context. The description only covers one conditional path and leaves the meaning of most fields and the overall derived-record workflow unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only adds meaning for verbatim_refs through the prerequisite instruction. The other 19 parameters, including required fields like id, kind, and summary, receive no conceptual explanation in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action and resource: '创建派生记录' (create derived record). It distinguishes the 'derived' nature of the record, which hints at its role among siblings, though it does not explicitly contrast with personal_add_followup or personal_add_hypothesis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete usage condition: if the source is a supplement from the current user, a verbatim capture must exist first and verbatim_refs must be set. This is clear context for a specific scenario, but it does not give exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
绑定已判定为个人材料的 turn receipt，原样保存完整用户消息。没有 preflight 或 preflight 判为非个人时拒绝写入；捕获后仍必须派生并 finalize。
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| turn_id | Yes | ||
| capture_id | Yes | ||
| captured_at | No | ||
| message_kind | No | ||
| conversation_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the behavioral disclosure burden. It discloses that writes are conditional on a passing preflight and that the tool rejects writes otherwise, plus the post-capture requirement to derive and finalize. It does not cover return values or idempotency, but for a narrow capture tool the key behaviors are stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The core purpose is front-loaded, and every clause adds either a precondition, a behavior, or a follow-up requirement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given six parameters, no output schema, and no annotations, the description provides the essential workflow guards but leaves parameter semantics and return/error behavior to inference. It is sufficient for an agent familiar with the domain, but not fully self-contained for a generic caller.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only loosely alludes to 'complete user message' (text) and 'turn receipt' (turn_id/capture_id). The optional parameters captured_at, message_kind, and conversation_id are entirely unexplained, leaving the agent to infer their meaning from names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: bind a pre-assessed personal turn receipt and save the full user message verbatim. It also clearly distinguishes the tool's role by referencing the preflight prerequisite and the required derive/finalize follow-up, placing it in an unambiguous pipeline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-not-to-use conditions: if there is no preflight or preflight marks the turn non-personal, writes are refused. It also states that after capture, derivation and finalization are mandatory, effectively instructing the agent on the required next steps within the sibling toolset.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
读取 v2 全局勘察。必须先完成当前轮次 turn preflight capture，并提供 capture_id；否则拒绝读取。
| Name | Required | Description | Default |
|---|---|---|---|
| view | No | survey | |
| query | No | ||
| capture_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It discloses a key behavior: the tool refuses to read when the precondition/capture_id is missing, and '读取' indicates a read-only operation. It does not cover output format or error details, but the refusal condition is meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The first sentence states the operation, and the second states the prerequisite and refusal behavior, keeping the most important usage constraint front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and 0% parameter schema descriptions, this description is the only guidance an agent has. It includes a crucial prerequisite but omits the meaning of the view and query parameters, and does not describe what the returned survey data contains. This leaves the agent unable to make informed choices about non-required parameters or expected outputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter meaning. It explains that capture_id must be provided from the preflight capture, but says nothing about view (survey/routing/full) or query. With one of three parameters explained, the description only partially compensates for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('读取') and a specific resource ('v2 全局勘察'), so the agent knows this is a read/catalog operation. It does not explicitly distinguish from siblings like personal_retrieve, but the resource and precondition narrow the purpose enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states when the tool is usable: only after the current turn's preflight capture is complete and a capture_id is provided; otherwise it refuses. However, it does not name alternative tools or state when to prefer a sibling tool for other kinds of retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
读取 capture→records 闭环状态，检查 pending、孤立捕获和链接漂移。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It conveys read-only intent via '读取' and names the checks it performs, which is useful. But it does not explicitly state that the call is side-effect-free or describe what kind of result the agent should expect beyond the named status categories.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise, front-loaded sentence with no filler. The action, object, and specific checks all fit in a compact line.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only status tool with no output schema, the description covers what the tool does and what it checks, which is sufficient to call it correctly. It could be slightly more explicit about return shape or prerequisites, but the low complexity makes that gap minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter documentation burden. The description adds value by naming the dimensions ('pending, orphaned captures, link drift') that the no-arg call will report on, going beyond the empty input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action ('读取', read) and a clear resource ('capture→records 闭环状态'), then lists the exact conditions checked: pending, orphaned captures, and link drift. This distinguishes it from sibling write/capture tools, which perform mutations rather than status inspection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended usage is implied: call this tool to inspect the capture-to-records closure status and detect pending/orphaned/link-drift issues. However, the description does not explicitly say when to prefer it over alternatives like personal_validate or personal_session_check, nor does it provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
关闭当前原话捕获的派生闭环。derived 必须已有至少一条双向链接记录；无需派生时必须写具体原因。回答前必须调用。
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | ||
| capture_id | Yes | ||
| disposition | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It reveals key constraints (precondition for 'derived', reason requirement for 'no-derivation-needed', and mandatory invocation), but omits side effects, idempotency, or error behavior. This is a moderate disclosure given the tool's mutation-like nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single brief sentence that front-loads the core purpose and the critical usage constraint. There is no wasted text; every clause conveys necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with no output schema and no annotations, the description covers the main workflow constraints (preconditions, mandatory call) but leaves out error conditions and the response format. It is adequate for a simple finalization action but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the meaning of the disposition enum values ('derived' and 'no-derivation-needed') and the reason requirement, but does not explicitly describe capture_id (though it is inferable from context). It adds some value but not full compensation for all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (closing the derivation loop) and the resource (current verbatim capture), and distinguishes itself from siblings by being the finalization step required before answering. It is clear enough but uses jargon ('派生闭环') that might be less explicit than 'finalize'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says '必须调用' before answering, providing a clear trigger for use. However, it does not list alternatives or conditions when this tool should not be used, leaving the choice among siblings to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
当前用户消息的强制内容预检。它持久化 turn receipt；个人经历、感受、关系、偏好、决定即使请求形式是润色/总结/看图，也会要求 capture。
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| turn_id | No | ||
| conversation_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It does disclose meaningful behavior: it persists a turn receipt and enforces capture of personal data across request forms. It does not explain side effects beyond persistence, failure modes, or whether it blocks or merely flags content, so transparency is only partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with two sentences that each add information: what the tool is and what it forces. It is appropriately sized, though the phrasing is somewhat dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema or annotations, and the description omits parameter semantics and the relationship to sibling tools. It explains purpose and a key behavior, but an agent would still be uncertain about how to fill the required fields and what will happen after the call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the parameters. It only implies that 'text' is the current user message and never addresses 'turn_id' or 'conversation_id'. This leaves most parameter meaning to inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a concrete function: a mandatory content preflight for the current user message, and it adds that it persists a turn receipt and enforces capture of personal categories. This distinguishes it from sibling capture tools even though it does not name one directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'mandatory' and the statement that capture is required even when the request is polishing/summarizing/image viewing give some guidance on when to use it. However, it does not explicitly contrast this with siblings like personal_capture_user_turn or personal_finalize_capture, leaving the exact pipeline placement implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
按 v2 事件、实体和情境卡读取 probe/deep。必须先完成当前轮次 turn preflight capture，并提供 capture_id；否则拒绝读取。
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | ||
| level | No | probe | |
| query | No | ||
| capture_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose a critical behavioral constraint: it will refuse to read unless capture_id is provided, which is valuable. It does not disclose whether the operation is purely read-only, any side effects, or what the response contains, so some transparency gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with high information density. The critical precondition is front-loaded, and every clause adds essential information: the data scope, the level, and the mandatory capture_id. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of input schema descriptions, output schema, and annotations, the description leaves important gaps: the meaning of 'ids' and 'query', the expected return structure, and any additional constraints. The tool has 4 parameters and 11 sibling tools, so the description alone is not enough for an agent to confidently invoke it without further inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. It does mention capture_id (required) and implicitly 'probe/deep' maps to the level enum, but it gives no explanation for the 'ids' and 'query' parameters. Therefore, it only partially compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a specific verb '读取' (read) and a specific resource ('probe/deep'), and it maps directly to the tool name personal_retrieve. It also distinguishes itself from sibling tools by stating the required precondition (preflight capture + capture_id) and the data scope (v2 events, entities, situation cards). No other sibling tool is described as reading probe/deep in this manner.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit context on when the tool can be used: after completing the current turn's preflight capture, and with a valid capture_id. It also states the when-not: without the capture_id it will refuse to read. However, it does not explicitly mention any alternative sibling tools or direct the agent to a different tool for other retrieval scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
回答或声称档案已更新前的硬闸门：turn receipt + capture 闭环 + 结构 + v2 完整性。个人 turn 必须传 turn_id，缺 capture 或 finalize 会失败。
| Name | Required | Description | Default |
|---|---|---|---|
| turn_id | No | ||
| allow_warnings | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does reveal meaningful behavior: it is a blocking gate, and missing capture or finalize causes failure. It also enumerates what is checked. However, it does not disclose whether the tool is read-only, what warnings mean, whether allow_warnings can bypass failures, or what the response shape looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loads the purpose before listing the main failure condition. The dense jargon ('closed loop', 'v2 completeness') slightly hurts comprehensibility, but the structure is efficient and every clause adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter check with no annotations and no output schema, the description is too thin. It omits allow_warnings semantics, response/error behavior, and any routing guidance against sibling validation tools. An agent would need to infer several important details before calling it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains that turn_id is required for personal turns, but it says nothing about allow_warnings, its default, its effect, or the format/expected values of turn_id. Half the parameter surface is effectively undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a hard pre-answer gate and lists the dimensions it checks: turn receipt, capture closed loop, structure, and v2 completeness. This goes beyond the bare name and distinguishes it from capture/finalize operations. However, 'v2 completeness' is left unexplained and no explicit verb such as 'validate' or 'check' appears.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit use window: run this before answering or claiming the profile has been updated. It also states a hard requirement for personal turns: turn_id must be supplied. It does not mention when not to use it or how it compares with siblings like personal_preflight_turn or personal_validate, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
校验 v2 结构，并明确区分失败、警告和干净。默认强制要求所有 capture 已完成派生闭环。只读。
| Name | Required | Description | Default |
|---|---|---|---|
| strict | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well: it discloses that the operation is read-only, that it distinguishes failure/warning/clean, and that by default all captures must have completed derivation closure. This goes beyond a generic 'validate' statement and gives an agent useful behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with purpose, and every sentence adds distinct value: validation scope, result categories, default behavior, and read-only safety. There is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately covers the tool's purpose, output categories, default behavior, and read-only nature. However, given that the only parameter 'strict' is entirely undocumented in both schema and description, the definition is not fully complete for an agent to invoke it with full confidence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one boolean parameter, 'strict', with no description and 0% schema description coverage. The description does not explain what 'strict' does or how it interacts with the default derivation-closure requirement, leaving the agent to guess whether setting strict to true relaxes or tightens validation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('校验' / validate) and a clear resource ('v2 结构' / v2 structure), and it clarifies the output categories of failure, warning, and clean. It does not explicitly differentiate from siblings by name, but the validate action is distinct enough among the listed siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys that this tool is for validating the v2 structure and implies it should be used when such validation is needed. However, it does not explicitly state when to use this over siblings, nor does it provide exclusions or alternative tool guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly defined role in the capture/derive/validate/session workflow, and the descriptions make boundaries explicit. The only mild overlaps are read-side tools (catalog vs retrieve) and validation gates (validate vs session_check), but these are distinguishable by scope.
All tools share a uniform personal_ prefix and snake_case style, with most following an imperative verb+object pattern. A few names are noun-like status/read tools (personal_catalog, personal_derivation_status), which is a minor deviation rather than chaos.
12 tools is within the ideal range and maps to a coherent personal-understanding workflow: preflight, capture, derive, finalize, validate, session-check, plus auxiliary reads and feedback. Each tool appears to earn its place in the lifecycle.
The surface covers ingestion, derivation closure, validation, retrieval, and session gating, which addresses most of the domain's needs. Missing explicit update/delete/correction operations for records leaves a minor gap for handling memory revisions, but agents can likely work around it via add_record/feedback.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Portable memory for AI agents: capture once, recall across Claude, Cursor, and any MCP client.
Person-owned AI memory that learns, not just stores — portable context for any MCP client.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/caix84476-netizen/personal-understanding'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
