A pure-Python library (built on ctypes) that lets you inspect, modify and search the memory of any running process in a few lines of Python โ Cheat Engine workflows on Windows, Linux and macOS!
pip install PyMemoryEditorTo also install the bundled GUI app (a Cheat Engine-style scanner), use the app extra:
pip install "PyMemoryEditor[app]"
pymemoryeditorFor faster scans on large processes, add the speed extra. It pulls in NumPy
and automatically vectorizes the numeric scan comparison loop โ ~10โ30ร faster on
selective scans:
pip install "PyMemoryEditor[speed]"To let an AI assistant drive the library over the Model Context Protocol, use
the mcp extra (see below):
pip install "PyMemoryEditor[mcp]"๐ Full guide at Read the Docs.
Related MCP server: ce-mcp
from PyMemoryEditor import OpenProcess
with OpenProcess(name="game.exe") as process:
# Scan the whole process for every address holding the value 100.
for address in process.search_by_value(int, value=100):
print(f"Found at 0x{address:X}")
# Read the current value, then write a new one back.
current = process.read_int(address)
process.write_int(address, current + 500)That's it โ read, write or scan another process in three lines, the same way on every platform.
PyMemoryEditor ships a Model Context Protocol server, so an AI assistant can run the whole loop itself:
"Find the health value in my game. It's 100 right now."
It scans, asks you to take damage, refines the matches, and hands you the address.
pip install "PyMemoryEditor[mcp]"
claude mcp add pymemoryeditor -- pymemoryeditor-mcpOr in any client that reads mcpServers JSON (Claude Desktop, editors, โฆ):
{
"mcpServers": {
"pymemoryeditor": {
"command": "pymemoryeditor-mcp",
"args": []
}
}
}Fourteen tools cover the full workflow, with scan results kept server-side behind a handle, so a 40 000-hit first scan costs a few tokens instead of your whole context.
Read the MCP guide to learn more.
Full documentation lives at pymemoryeditor.readthedocs.io โ installation, the Cheat Engine workflow, every method and parameter, the GUI app guide, platform notes and troubleshooting.
A quick map of where to go:
๐ฎ Game modding & speedrunning tools โ the classic Cheat Engine use case.
๐ฌ Debugging & introspection โ inspect live state without attaching a debugger.
๐ Observability tooling โ sample variables in a running process for telemetry.
๐ Security & reverse-engineering research โ on systems you own or are authorized to test.
๐ Learning โ the bundled app is a great teaching tool for how memory scanning works.
Responsible use. PyMemoryEditor talks to other processes through OS-level APIs. Only point it at processes you own or have explicit permission to inspect.
Pull requests, bug reports and feature ideas are very welcome. Read
CONTRIBUTING.md for the development setup, test layout and
the small set of platform-specific quirks to be aware of.
If PyMemoryEditor helped your project, please โญ the repo โ it's the easiest way to support the work and to help others discover the library.
Released under the MIT License โ free for personal and commercial use.
Detach from a process and drop its scan result sets.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds the concrete consequence beyond the flags: scan result sets are dropped and the agent merely "detaches" rather than terminating the process. It does not clarify what happens to a session's other state or whether the effect is reversible, which keeps it short of a 5.
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 front-loaded sentence with no filler; the destructive consequence is stated immediately rather than buried.
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?
An output schema exists, so return values need no explanation, and the destruction of scan results is disclosed. However, for a destructive, non-idempotent, open-world mutation tool, the description omits permission/session prerequisites and any when-to-use context.
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?
There is a single parameter, session_id, with 0% schema description coverage, so the schema contributes nothing. The description implies the identifier is tied to the process being detached from, but never states its format, origin, or relationship to open_process's session, so it only partially compensates.
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?
States a specific verb ("Detach from") and resource ("a process") plus the side effect on scan result sets, which operationally distinguishes it from open_process and the scan/read siblings. It does not explicitly name a sibling as the alternative, but the action is unambiguous.
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?
There is no statement of when to call this versus alternatives (e.g., after finishing with a session, or versus simply leaving it open). Usage is only inferable from the verb, with no prerequisites or exclusions given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reverse-scan for static pointer paths that reach an address.
The inverse of resolve_pointer_chain, and the step that turns a
throwaway find into something reusable: an address from scan_value
is different every run, but a path rooted in a module's image is the
same recipe every time. Run this on the address you confirmed, then
replay the best path in the next run with resolve_pointer_chain.
:param target_address: the dynamic address to find paths to.
:param max_depth: pointer levels to follow. Cost grows sharply with
depth; 1โ4 is the useful range and 3 is a good default. A chain
needs at least one level, so 0 clamps to 1 rather than to the
default โ and null means "use the default", as it does for
every argument here.
:param max_offset: largest offset a single hop may add โ effectively
the assumed struct size. Larger finds more and noisier paths.
An explicit 0 is meaningful rather than "unset": it keeps only
hops that point exactly at the address. null means "use the
default" (1024) โ it used to mean 0, i.e. the narrowest search
possible, which is the opposite of what a client sending null for
an unset field intends.
:param max_results: stop after this many paths.
This is the most expensive tool here, and it runs in two phases: it maps every pointer in the target's writable memory, then walks that map backwards. Only the first phase reports progress, so the server's time budget bounds it precisely and the second phase only between paths โ a deep walk that finds nothing can still run long. Expect seconds to minutes on a large process, and start shallow.
| Name | Required | Description | Default |
|---|---|---|---|
| max_depth | No | ||
| max_offset | No | ||
| session_id | Yes | ||
| max_results | No | ||
| target_address | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, open-world, non-destructive, non-idempotent behavior, but the description adds substantial operational context beyond them: two-phase execution, progress reporting only in the first phase, time-budget limitations, seconds-to-minutes runtime, and sharply increasing cost with depth. These are exactly the behavioral traits an agent needs before invoking an expensive scan.
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 front-loaded with purpose and structured by parameter, and its length is largely justified by the tool's complexity and expense. Still, the historical note about max_offset formerly meaning 0 and some repeated null-default phrasing are more verbose than the agent strictly needs.
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?
An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description is otherwise very complete for a complex, expensive read operation, but omitting session_id semantics and including null guidance that conflicts with the integer-only schema keep it from being fully complete.
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?
With 0% schema description coverage, the description carries the burden and does so well for max_depth, max_offset, and max_results, including clamping, default/null behavior, and cost implications. However, the required session_id parameter is never described, and the stated null semantics for integer fields are not reflected in the input schema, leaving a notable gap.
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?
States a specific verb (reverse-scan) and resource (static pointer paths that reach an address), and explicitly positions itself as the inverse of resolve_pointer_chain. An agent can distinguish it from scan_value, refine_scan, and resolve_pointer_chain without opening any schema.
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?
Gives direct usage guidance: run this on the address you confirmed, then replay the best path with resolve_pointer_chain. It also names the relevant sibling context (scan_value, resolve_pointer_chain) and advises starting shallow, so when and how to use it are explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Page through the target's memory map.
:param writable_only: keep only writable regions โ where a program's
mutable state (the values worth scanning for) lives.
:param executable_only: keep only executable regions โ code.
:param path_filter: keep only regions backed by a file whose path
contains this substring.
:param limit: rows per page. The server caps it โ see
server_info().limits.max_page_size.
:param offset: rows to skip, for paging.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| session_id | Yes | ||
| path_filter | No | ||
| writable_only | No | ||
| executable_only | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and openWorld, so safety is covered. The description adds genuinely new behavior: the server caps the page size and points the agent to server_info().limits.max_page_size, plus the semantic meaning of each region class. That is useful operational context beyond the annotations.
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 lead sentence is front-loaded and the RST ':param' block is scannable. The formatting is slightly verbose for what it conveys, but no sentence is 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?
With an output schema present, return values need not be described, and the pagination and filter semantics are well covered. The only gap is the undocumented required session_id parameter, which is a minor omission for an otherwise complete definition.
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 coverage is 0%, so the description carries the full burden and mostly meets it: it explains writable regions ('mutable state'), executable regions ('code'), substring matching for path_filter, and the cap/reference for limit. Only session_id, the single required parameter, is left unexplained.
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?
States a specific verb and resource ('Page through the target's memory map'), which is unambiguous on its own. It does not explicitly differentiate from siblings like list_processes or list_scan_results, but the resource name is distinct enough that confusion is unlikely.
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?
Usage is implied through the filter parameters (e.g. writable_only is framed as 'the values worth scanning for'), which hints at a scan-preparation workflow. However, it never states when to call this versus siblings such as list_scan_results or process_info, nor any prerequisites beyond the session_id requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List running processes this server is allowed to open.
:param name_filter: keep only processes whose name contains this
substring, case-insensitively. Use it โ an unfiltered list on a
desktop is several hundred entries of pure noise.
:param limit: maximum entries to return, capped at
server_info().limits.max_page_size.
:param offset: entries to skip, for paging. It exists because the cap
used to be a different number from the one server_info
advertised, with no way past it โ so everything after the first
page was simply unreachable.
Processes blocked by the server's policy are omitted, and the result says how many were hidden so the absence of an expected target is distinguishable from it not running.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| name_filter | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly/idempotent/non-destructive), and the description adds genuinely new behavior: policy-blocked processes are omitted and the count of hidden entries is reported so a missing target is distinguishable from a non-running one. It also ties the limit cap to server_info().limits.max_page_size, which is non-obvious behavioral coupling.
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?
Front-loaded with purpose, then parameters, then result behavior โ good ordering. The historical aside about the old cap mismatch explains why offset exists but is longer than needed, and the docstring-style ':param' formatting is slightly unusual for a tool description.
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?
With an output schema present the description needn't enumerate return fields, yet it still explains the notable one (the hidden-process count) and the permission/policy filtering. All three optional parameters are covered, so an agent has everything required to call this correctly.
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 carries the full burden and does so for all three parameters: name_filter is a case-insensitive substring match, limit is capped at the server's advertised max page size, and offset is for paging past the first page. This adds real semantics beyond the bare schema titles and defaults.
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?
States a specific verb and resource ('List running processes') plus a meaningful scope qualifier ('this server is allowed to open'), so the agent knows the list is permission-filtered rather than exhaustive. It does not explicitly name or contrast with siblings like process_info or open_process, but the verb+resource pairing is unambiguous.
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?
Gives direct operational guidance โ 'Use it' for name_filter because an unfiltered list is 'several hundred entries of pure noise' โ and explains that offset exists for paging past the advertised cap. It stops short of naming when to prefer this tool over siblings (e.g., before open_process/process_info), so alternatives are left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Page through a result set, reading each address's current value.
Values are read live, so calling this twice on a set that is still changing is itself a useful signal: the address whose value tracks what you see in the target is the one you want.
:param limit: rows per page. The server caps it โ see
server_info().limits.max_page_size.
:param offset: rows to skip.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| scan_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description correctly spends its words elsewhere: it discloses that values are read LIVE rather than cached and that the server enforces a page-size cap referencing server_info().limits.max_page_size. That is meaningful context beyond the structured fields.
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 front-loaded with purpose, but the middle sentence about reading live values and tracking the target is discursive and bleeds into the parameter block without separation, making it denser than needed for two trivial pagination params.
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?
An output schema exists, so return-format explanation is not required, and pagination is addressed. However, the required scan_id (its origin in scan_value/scan_pattern/refine_scan) and any relationship to the other read tools are left entirely 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%, so the description must carry the load, and it documents only limit ('rows per page') and offset ('rows to skip') โ semantics largely derivable from the names. The required scan_id parameter is never explained: what a scan id is, where it comes from, or which sibling produces it.
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?
States a specific verb ('page through') and resource ('a result set'), plus what is returned ('each address's current value'). It is distinguishable from single-address read_value and from refine_scan by implication, though it never names a sibling explicitly.
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 offers a usage heuristic (call twice on a changing set to identify the live-tracking address), which is genuine guidance but specialized. It never states when to use this instead of read_value or refine_scan, so the routing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attach to a process and return a session_id for the other tools.
:param pid: the process id to open. Preferred โ it is unambiguous.
:param name: a process name (or fragment) to resolve instead, matched
case-insensitively as a substring. When several processes match,
no process is opened and the candidates are returned for you to
pick a pid from.
Pass exactly one of the two. The returned session stays open until
close_process or server shutdown; reuse its id rather than
reopening the same target, since each open costs a handle and resets
the cached region map.
At most max_open_sessions (see server_info) can be open at
once; reaching it is refused, not rotated, so close_process a
target you are done with.
Attaching to a process the operator has not pre-approved requires the user's approval, asked for at the moment you call this. Say which process you want and why; if the request is refused, report that rather than trying a different target.
| Name | Required | Description | Default |
|---|---|---|---|
| pid | No | ||
| name | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover safety hints (readOnly=false, openWorld=true). The description adds substantial beyond-schema behavior: each open costs a handle, resets the cached region map, sessions persist until close_process or shutdown, the max_open_sessions cap is refused rather than rotated, and attaching to unapproved processes requires live user approval. This is exactly the operational context an agent needs.
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?
Front-loaded with the core action and return value, then constraints. Every sentence carries unique information, though the approval paragraph and session-limit paragraph make it slightly dense for a two-parameter tool.
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?
No output schema exists, yet the description names the returned session_id and even the ambiguous-match candidate return. For a stateful, approval-gated open operation, no relevant behavior is left unstated.
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 carries the full burden and does so: pid is the process id and preferred; name is matched case-insensitively as a substring, and ambiguous matches return candidates rather than opening anything. Both params are given meaning the schema lacks.
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?
States a specific verb+resource ('attach to a process') and names the concrete return value ('session_id'), which immediately distinguishes it from read-only siblings like process_info and from the terminating close_process.
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?
Explicitly says 'pass exactly one of the two', prefers pid as unambiguous, explains the ambiguous-name fallback, and instructs to reuse the session id rather than reopening. It also names close_process as the paired alternative and the condition for using it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize an open target: bitness, address space, modules, threads.
The module list is the useful half for reverse engineering: a module's
base_address moves every launch (ASLR) but offsets inside it do
not, so base + offset is how a found address becomes a recipe that
survives a restart. See find_pointer_paths for discovering those
offsets and resolve_pointer_chain for replaying them.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so safety is covered. The description adds genuine value beyond them by explaining ASLR: a module's base_address shifts each launch while internal offsets persist. It stops short of auth/rate-limit or freshness caveats.
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 first sentence is front-loaded and complete on its own, immediately naming the returned fields. The second paragraph is longer than strictly necessary for a one-parameter read tool, but its content earns most of its space.
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?
An output schema exists, so return values need no prose, and the annotations cover the safety profile. The description supplies the missing conceptual context (ASLR, base+offset) and next-step tools, leaving only the session_id semantics undocumented.
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 lone session_id parameter is never mentioned in the description. 'Open target' only loosely implies the session must come from open_process; the parameter's origin and expected format are left entirely 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?
States a specific verb and resource ('Summarize an open target') and enumerates the exact payload (bitness, address space, modules, threads), which cleanly distinguishes it from list_processes and list_memory_regions. An agent can tell what this returns without opening the schema.
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?
Implicitly scoped to an already-open target, but never says when to reach for this versus list_processes or list_memory_regions. The references to find_pointer_paths and resolve_pointer_chain guide the surrounding workflow rather than this tool's selection, so guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one value from an address.
:param address: hex string, e.g. "0x7FFD1234".
:param value_type: int, float, bool, str or bytes.
:param bufflength: width in bytes. Required for str / bytes
(nothing else says how far to read); defaults to intโ4, floatโ8,
boolโ1 for the numeric types.
Numeric widths are restricted to the ones every path agrees on:
1, 2, 4 or 8 for ``int``, 4 or 8 for ``float``, 1 for ``bool``.
Anything else is refused rather than half-supported. Text widths
are capped โ see ``server_info().limits``.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | ||
| bufflength | No | ||
| session_id | Yes | ||
| value_type | No | int |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral detail beyond that: unsupported widths are 'refused rather than half-supported', text widths are capped via server_info().limits, and default widths vary by value_type.
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 purpose sentence is front-loaded, then each parameter is documented in a compact line; the trailing paragraph covers only non-obvious constraints (allowed widths) that an agent could otherwise get wrong. 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?
A mutation-free read tool with an output schema, so return values need no explanation, and the description covers formats, type-specific defaults, refusal behavior, and limit lookups. Session handling and the exact response shape are the only omissions, and the output schema likely covers the latter.
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 carries the full burden, and it delivers: address format with a hex example, the five accepted value_type strings, and bufflength semantics including per-type defaults and validity ranges. Only session_id is left undocumented, which keeps it from a 5.
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?
States a specific verb and resource ('Read one value from an address'), which cleanly separates it from write_value, scan_value, and the pointer tools. It does not explicitly name a sibling or boundary condition, so it falls short of a 5.
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?
Usage is implied rather than stated: the parameter docs reveal when bufflength is mandatory (str/bytes) and point to server_info().limits for text caps, which is a useful cross-tool routing hint. But there is no explicit statement of when to prefer read_value over scan_value, refine_scan, or resolve_pointer_chain.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Narrow an existing result set. The second step, repeated.
This is Cheat Engine's "Next Scan", and it is what makes the whole workflow work: change the value in the target (take damage, spend a coin), then keep only the addresses that changed to match. Two or three rounds usually collapse tens of thousands of candidates to one.
It re-reads the addresses already in the set rather than walking memory
again, so it is orders of magnitude faster than a fresh scan and cannot
find addresses the original scan missed. Each refine returns a new
scan_id; the previous set stays live, so a refine that narrows too
far (down to zero) can be retried from the one before it.
:param scan_id: the set to narrow.
:param scan_type: comparison to apply โ the same names scan_value
takes. For str / bytes sets only exact / not_exact
are available.
:param value: the value to compare against.
:param end_value: upper bound for between / not_between.
| Name | Required | Description | Default |
|---|---|---|---|
| value | No | ||
| scan_id | Yes | ||
| end_value | No | ||
| scan_type | No | exact |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations. It discloses that each refine returns a NEW scan_id, that the prior result set remains live, and that shrinking to zero is recoverable โ behaviorally important and consistent with idempotentHint=false and readOnlyHint=true. It also quantifies expected convergence (two or three rounds) and the performance profile versus a fresh scan.
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?
Purpose is front-loaded and the body is dense with usable detail, but the framing line 'and it is what makes the whole workflow work' and 'The second step, repeated.' add rhetorical padding without new information. Every other sentence earns its place.
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?
With an output schema present, return values need not be re-explained, and the description already covers the key one (new scan_id). Combined with full parameter semantics, workflow guidance, and the retry/lineage model for previous scan sets, an agent has everything needed to invoke this correctly.
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 carry the load, and it does: scan_id is the set to narrow, scan_type is the comparison sharing scan_value's names with a str/bytes restriction to exact/not_exact, value is the comparison target, and end_value is the upper bound for between/not_between. All four params are given meaning absent from the 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?
States a specific verb and resource (narrow an existing result set) and positions it precisely as the follow-up to a fresh scan. It names the sibling whose scan_type vocabulary it shares (scan_value) and explains the core distinction: it re-reads existing addresses rather than walking memory, so it cannot find what the original scan missed.
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?
Gives an explicit workflow trigger (change the value in the target โ take damage, spend a coin โ then keep addresses that changed to match) and an explicit exclusion (it cannot find addresses the original scan missed, so use a fresh scan for that). It also documents the retry path: the previous set stays live when a refine narrows to zero.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Walk a known multi-level pointer chain to its final address.
Replays the recipe a Cheat Engine table records โ
"game.exe"+0x10F4F4 -> [+0x0] -> [+0x158] โ which is the form that
survives a restart. Combine with process_info's module
base_address to build base_address for the current run.
:param base_address: where the chain starts, hex. Usually
module_base + static_offset.
:param offsets: the chain's offsets in order, as hex strings
(["0x0", "0x158"]). Negative offsets are allowed
("-0x8") โ walking backwards through a struct is ordinary in a
published recipe. The last one is added without a final
dereference, so the result is the address the value lives at โ read
it with read_value. Pass an empty list to dereference
base_address once.
| Name | Required | Description | Default |
|---|---|---|---|
| offsets | No | ||
| session_id | Yes | ||
| base_address | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds meaningful behavior beyond them: the last offset is added without a final dereference so the result is the address the value lives at, and negative offsets are permitted. That yields exactly the semantics an agent needs to interpret the output.
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?
Front-loads the one-line purpose before the recipe example and param details. Detailed but every sentence carries information (dereference semantics, negative offsets). The docstring-style layout is slightly verbose relative to what a tool description needs, but nothing is padding.
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?
An output schema exists, so return values needn't be explained, and the description covers purpose, mechanics, and the relevant parameters. The only shortfall is the absent session_id context and no explicit statement of when to use this versus the path-finding sibling.
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 coverage is 0%, so the description carries the full burden, and it does well: base_address is defined as hex, usually module_base + static_offset; offsets are hex strings with negative values allowed, ordering explained, and the last-offset/empty-list edge cases called out. Only session_id goes undescribed, which is a minor gap for an otherwise thoroughly documented parameter set.
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?
States a precise verb+resource ("Walk a known multi-level pointer chain to its final address") and the word "known" distinguishes it from the sibling find_pointer_paths, which discovers paths. An agent can tell what this does and how it differs from neighbors without opening a schema.
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 implies the workflow (combine with process_info's module base_address to build the start address; read the result with read_value), which is useful context. But it never explicitly states when to choose this over find_pointer_paths, nor any exclusion or precondition beyond the build-up hint. Adequate but implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan for a byte pattern (an AOB scan) with ? wildcards.
The IDA / Cheat Engine technique for finding a structure or a piece of
code whose address moves between builds but whose surrounding bytes do
not: "48 8B ? ? 00 00 89". Returns a scan_id like
scan_value.
:param pattern: space-separated hex bytes, where ? or ?? is a
single-byte wildcard.
Note that this covers the target's readable, non-shared regions โ
heap, stack and anonymous mappings. File-backed code (a .dll /
.so / .dylib image) is a shared mapping and is deliberately
excluded, so patterns matching instructions inside a loaded module will
not be found here. Reach module code through process_info's module
bases plus a static offset instead.
| Name | Required | Description | Default |
|---|---|---|---|
| pattern | Yes | ||
| session_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, non-destructive, openWorld, non-idempotent), so the bar is lower. The description adds genuinely valuable behavioral scope: the scan covers only the target's readable non-shared regions (heap, stack, anonymous mappings) and excludes shared/file-backed mappings, which directly affects whether a call can succeed.
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?
Front-loaded with the core purpose, then rationale, then the scope caveat, so an agent can stop reading early. Slightly verbose with an embedded RST ':param:' block, but every sentence carries 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?
With an output schema present, return values need no explanation, and the description still notes the returned scan_id. Combined with the pattern syntax and the region-coverage caveat, an agent has everything needed to call this correctly and interpret a partial result.
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 coverage is 0%, so the description must carry the burden. It fully specifies the pattern parameter's syntax ('space-separated hex bytes, where ? or ?? is a single-byte wildcard') with a concrete example, and session_id is a self-evident session handle. This compensates well for the missing schema 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?
States a specific verb and resource ('Scan for a byte pattern (an AOB scan) with ? wildcards') and immediately disambiguates from the sibling scan_value by noting it returns a scan_id 'like scan_value'. An agent can identify this as the address-independent pattern-matching primitive without opening the schema.
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?
Explains when this technique applies (address moves between builds, surrounding bytes do not) and, critically, when it does NOT: file-backed module code is deliberately excluded and should be reached via process_info's module bases plus a static offset. This names both the exclusion and the alternative path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan the target's memory for a value. The first step of the loop.
This is Cheat Engine's "First Scan". It returns a scan_id, a match
count and a few sample addresses โ not the addresses themselves, which
routinely number in the tens of thousands. Narrow the set with
refine_scan after the value changes in the target, and repeat until
a handful remain; then read them with list_scan_results.
:param value_type: int, float, bool, str or bytes.
:param value: the value to match. Hex is accepted for int
("0x64") and required for bytes ("DEADBEEF").
:param scan_type: exact (default), not_exact, bigger,
bigger_or_exact, smaller, smaller_or_exact, between
or not_between.
:param end_value: the upper bound, required by between /
not_between and rejected otherwise.
:param bufflength: width in bytes โ 4 for a typical int, 8
for a double. Leave at 0 for the default (intโ4, floatโ8,
boolโ1) or, for str / bytes, to infer it from value.
Numeric widths are restricted to 1, 2, 4 or 8 for ``int``, 4 or 8
for ``float``, and 1 for ``bool``; anything else is refused rather
than half-supported. Text is capped, inferred or not โ see
``server_info().limits``.
:param writable_only: restrict the scan to writable memory (the default). A value the program changes lives in writable memory, so this usually cuts the work and the false positives by an order of magnitude. Turn it off only when hunting constants.
A scan stops early at the server's result cap or time budget; when it
does, the result sets partial and explains what to narrow. Refining
a partial set can converge on the wrong address, because the right one
may never have been in it.
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes | ||
| end_value | No | ||
| scan_type | No | exact | |
| bufflength | No | ||
| session_id | Yes | ||
| value_type | Yes | ||
| writable_only | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the generic read-only/idempotency profile; the description adds substantive behavior: it returns a scan_id, match count and sample addresses rather than the full address set, it can stop early at a result cap or time budget and set 'partial', and it warns that refining a partial set can converge on the wrong address. That is real operational context an agent must have.
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?
Purpose and the loop are front-loaded, and the per-parameter block is genuinely needed given 0% schema coverage. It is longer than a two-line tool warrants and the bufflength paragraph is dense, but almost every sentence carries load.
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?
An output schema exists, yet the description still closes the loop on what comes back (scan_id, count, samples) and on the failure mode (partial results misdirecting a refine). For a 7-parameter stateful scan entry point with no schema documentation, nothing an agent needs to call it correctly is missing.
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 carries the entire burden and does: valid value_type tokens, hex format for int and bytes, the full scan_type enumeration, end_value's conditional requirement, bufflength's per-type widths and the 1/2/4/8 restriction, and the default/rationale for writable_only. Only session_id goes undocumented, and its meaning is unambiguous.
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?
States a specific verb and resource ('Scan the target's memory for a value') and frames it as the first step of a named loop. It is immediately distinguishable from refine_scan (narrowing) and list_scan_results (reading), so an agent can pick it without opening any schema.
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?
Gives an explicit workflow: scan first, refine_scan after the value changes, list_scan_results at the end. It also names the two alternative scan entry points implicitly (refine_scan, scan_pattern) and states the condition for using writable_only vs not ('turn it off only when hunting constants').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report the server's capabilities, limits and open sessions.
Call this first. It answers the questions whose wrong answer wastes the most turns: whether writing is enabled at all, which processes are reachable, how long a scan may run, and which sessions are already open from earlier in the conversation.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds real value by disclosing what the response reveals about the server's operating envelope, notably whether writing is enabled and which sessions persist. It stops short of describing output shape, but an output schema exists.
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?
Front-loads the purpose, then the imperative 'Call this first.' The final clause mildly restates 'open sessions' from the first sentence, costing a little economy, but the elaboration on wasted turns earns its place.
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 no-param, read-only capability probe with an output schema, the description supplies everything needed: what it reports, when to call it, and why it matters. No gaps for an agent to fill.
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?
Zero parameters, so there is nothing to document and the baseline is 4. The description correctly implies the tool takes no arguments and returns a self-describing capability report.
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?
States a specific verb+resource pair (report the server's capabilities/limits/sessions) that is clearly distinct from the targeted siblings like list_processes and scan_value. An agent can tell this is the meta/overview tool without opening any schema.
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?
Gives explicit ordering guidance ('Call this first') and justifies it by naming the decisions it resolves (write-enabled, reachable processes, scan duration), which is exactly the when-to-use context an agent needs before touching the mutating siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a value to an address. Absent when the server is --read-only.
The previous value is read first and returned as previous_value, so
the change is reversible: to undo, call this again with that value.
Nothing else in this server can put it back.
:param address: hex string, e.g. "0x7FFD1234".
:param value_type: int, float, bool, str or bytes.
:param value: the value to write. Hex for bytes.
:param bufflength: for numbers, the exact write width โ 1, 2, 4 or 8
for int, 4 or 8 for float, 1 for bool.
For ``bytes`` it is a maximum number of bytes, which truncates and
never pads. For ``str`` it caps **characters**, not bytes, so
non-ASCII text can overwrite more bytes than the number you pass:
``bufflength=2`` with ``"ๆฅๆฌ่ช"`` writes ``"ๆฅๆฌ"`` โ six bytes.
The result's ``previous_value_bufflength`` always reports the span
that was actually replaced, so check it rather than assuming.
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes | ||
| address | Yes | ||
| bufflength | No | ||
| session_id | Yes | ||
| value_type | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=true, so the safety bar is lower. The description adds vital context: previous value is read and returned as previous_value, and 'Nothing else in this server can put it back,' which is critical for an agent making destructive writes. It could go further on permission or failure behavior.
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?
Information-dense but front-loaded: reversibility and availability appear first, then parameter details. The unicode example is slightly verbose but earns its place by illustrating a non-obvious edge case. No filler sentences.
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?
With an output schema present, the description correctly avoids detailing return values, but still tells the agent that previous_value and previous_value_bufflength are returned, which matters for reversing the write. It covers the destructive nature, the read-only mode, and all parameter quirks. Complete for a low-level memory-write tool.
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 defines address format (hex), valid value_type values, bufflength semantics per type (write width for numbers, max bytes truncating for bytes, character cap for str), and includes a concrete unicode hazard example. This is far beyond a baseline and fills all gaps.
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?
States a specific verb+resource ('Write a value to an address') with a clear scope, and the read-back semantics distinguish it from read_value. The context note 'Absent when the server is --read-only' also clarifies availability.
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?
Explicitly describes the reversibility mechanism and instructs how to undo ('call this again with that value'), and references the read-only mode constraint. However, it does not mention read_value or scan_value as alternatives for reading, so no sibling routing beyond the implicit inverse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0close_processfind_pointer_pathslist_memory_regionslist_processeslist_scan_resultsopen_processprocess_inforead_valuerefine_scanresolve_pointer_chainscan_patternscan_valueserver_infowrite_valueScored across 14 tools
The core scan/refine/read workflow is clearly delineated with distinct purposes for each tool. Minor potential for confusion between resolve_pointer_chain and find_pointer_paths, but descriptions clarify that they are inverses.
Most tool names follow a verb_noun pattern (scan_value, read_value, write_value, open_process, close_process). Some deviate (process_info, server_info) where the noun precedes the verb, but overall consistent and readable.
14 tools are well-scoped for a memory editing server, covering the full workflow from process attachment through scanning, refining, pointer analysis, and writing. Each tool has a distinct, necessary role.
The toolset covers the complete Cheat Engine-style workflow: open/close process, scan, refine, list results, read/write, resolve/find pointer chains. A minor gap might be a bulk read or write operation, but the core lifecycle is fully supported.
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Persistent memory for AI agents. Semantic search, memory graph, W3C DID identity.
