PyMemoryEditor

Detach from a process and drop its scan result sets.

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.

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.

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.

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.

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.

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.

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``.

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``.

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.

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.

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.

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.

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.