AI Memory — Processes
AI-first map of process attachment and memory process readers.
Memory / Process Discovery Map
Reference map for core process readers, process memory access, pointer chains, pattern scanning, PE helpers, modules, code caves, and backend selection.
Optional package-specific readers belong in nuget/.
Select a process and read its modules
In an EyeAuras script with the Memory module loaded, list candidates first:
using EyeAuras.Memory;
foreach (var info in LocalProcess.GetProcesses())
Log.Info($"{info.Id} {info.ProcessName}");
Pass the selected PID to this ordinary C# helper. The returned module snapshot outlives the reader; its addresses remain meaningful only while the target and its modules exist.
using System.Collections.Generic;
using EyeAuras.Memory;
static IReadOnlyList<ProcessModuleInformation> ReadModules(int processId)
{
using var process = LocalProcess.ByProcessId(processId);
return process.GetProcessModules();
}
ProcessModuleInformation supplies ModuleName, FilePath, BaseAddress
(IntPtr) and Size in bytes. The reader owns its handles; process.Memory is
borrowed. Keep the reader open for subsequent reads instead of returning its
Memory from a using block. ByProcessName accepts names with or without .exe;
use a PID to select a particular instance.
For an interactive script, obtain a window through the OSD picker:
using EyeAuras.Memory;
using EyeAuras.Shared.Osd;
var window = await GetService<IOsdSelectionService>().PickWindow();
{
using var process = LocalProcess.ByProcessId(window.ProcessId);
foreach (var module in process.GetProcessModules())
Log.Info(module.ModuleName);
}
The window handle is borrowed. Picker cancellation exits through its cancellation
exception; it does not provide a process to open. IsValid describes the reader,
not a guarantee that the target will stay alive. See selection.
A helper with an open reader, an actual module name and a known byte offset of
an int field can read it as follows:
using EyeAuras.Memory;
using EyeAuras.Memory.Scaffolding;
static int ReadModuleInt32(IProcess process, string moduleName, int offset)
{
using var memory = process.MemoryOfModule(moduleName);
return memory.Read<int>(memory.BaseAddress + offset);
}
GetProcessModule matches names without case sensitivity and throws
ArgumentException when absent; TryFindProcessModule returns a Boolean.
MemoryOfModule creates a view, but reads take absolute addresses and do not
automatically enforce its bounds. Disposing the view does not dispose the process.
For signatures use pattern scanners; for scalar, array and
pointer-chain operations see the Memory reference.
In an embedded host, declare UseMemory() and await EnsureReadyAsync() with
the runtime and Memory modules available. Metadata references alone do not
register ILocalProcessBuilder; LocalProcess throws InvalidOperationException
without it. See Embedded SDK.
User Intents
- Attach to a process and read/write memory.
- Choose local, native local, kernel-driver, or MPFS backend.
- Attach from a PID selected via window picker.
- Resolve modules, imports, exports, PE metadata.
- Follow pointer chains.
- Resolve a live local thread id or thread handle to its TEB address.
- Enumerate processes through a kernel
_EPROCESSlist when the backend can read kernel virtual memory. - Read process parameters, threads, and VAD-backed memory regions through a
trusted
_EPROCESSaddress when the backend can read both kernel virtual memory and the target user-mode address space. - Build simple memory-backed entity/object wrappers.
- Scan byte/string patterns.
- Enumerate memory regions and protections.
Concept Model
IProcessis the top-level target process abstraction.IProcessMemoryexposes process memory facade.IMemoryAccessordescribes the memory context and range;IMemoryReaderandIMemoryWritersupply reading and writing.IMemoryBackendperforms low-level operations.RemoteMemoryObjectis a small helper base for objects that represent a known address inside anIMemoryview.EyeAuras.Memory.Sharedcontains contracts.EyeAuras.Memory.Metadatacontains compile-time SDK-facing memory facades such asLocalProcessand public local-process contracts.EyeAuras.Memorycontains the local process implementation and registers the runtime provider for theEyeAuras.Memory.Metadatafacade when loaded.EyeAuras.Memory.KDcontains kernel-driver-backed access.EyeAuras.Memory.MPFScontains MemProcFS / LeechCore / VMM access.- Backends do not expose identical control capabilities.
API Details
IProcess-IsValid,ProcessName,ProcessId,Memory,GetProcessModules(),GetThreads(),VirtualQuery(...),GetMemoryRegions().IProcessMemory- process memory facade.IMemoryReader/IMemoryWriter- typed reads/writes and pointer-chain operations.IMemory- memory view, often module-scoped throughMemoryOfModule(...).RemoteMemoryObject- base class for address-backed memory object wrappers.IMemoryBackend- backend implementation contract.IProcessControlApi- allocation, protection,CreateThread, synchronousExecuteCode, suspend/resume, APC where supported.IProcessSupportsManualMapping- opt-in marker for backends that can stage and synchronously execute manual-mapping code throughIProcessplusIProcessControlApi.LocalProcess- normal local user-mode reader. In embedded/package usage the public facade is available from metadata assemblies, but the implementation requires theEyeAuras.Memorymodule/package to be present and loaded. For embedded apps this means declaringUseMemory()and awaitingEnsureReadyAsync(...)before calling the static facade.ILocalProcessBuilder- public builder contract registered by the loaded Memory module.LocalProcessforwards to this builder and fails clearly when the module was not loaded.NativeLocalProcess- native local backend with permission tuning.KDProcess- kernel-driver-backed reader.LCProcess,ILCProcessBuilder- MPFS/LeechCore/VMM readers.MemoryExtensionsForPatterns,BytePattern,StringPattern- signature scanning.MemoryExtensionsForCodeCaves,CodeCaveEntry- module-scoped code-cave enumeration; default scanning targets readable executable sections and treats0x00,0xCC, and0x90runs as valid cave padding.MemoryExtensionsForImports,ProcessExtensions.ReadExports,ProcessPEExtensions- PE helpers.MemoryExtensionsForEprocess- backend-neutral helpers for reading high-level process, module, thread, process-parameter, and VAD-backed memory region facts from_EPROCESS, PEB, loader-list, thread-list, and VAD records through anyIMemoryReaderthat can read the relevant virtual memory.MemoryExtensionsForTebPeb- backend-neutral helpers for reading a PEB address from a TEB, loaded modules from PEB loader lists, and process startup parameters fromRTL_USER_PROCESS_PARAMETERSthrough anyIMemoryReaderthat can read the target user-mode address space. Local live-OS thread-to-TEB queries belong to the internalWin32NativeShared, not this public memory-reader surface.ReadProcessInformation- reads PID and image-name information from an_EPROCESSaddress without exposing raw kernel structures.ReadPebAddressViaEprocess- reads the PEB pointer referenced by_EPROCESS; for WOW64 processes it returns the WOW64 PEB when available.ReadProcessModulesViaEprocess- reads loaded modules through the PEB referenced by_EPROCESSand returnsProcessModuleInformation.ReadProcessParametersViaEprocess- reads startup metadata such as image path, command line, current directory, desktop/window metadata, and environment pointer through_EPROCESS -> PEB.ReadProcessThreadsViaEprocess- walks_EPROCESS.ThreadListHeadand returns high-levelProcessThreadInformationrecords.ReadMemoryRegionsViaEprocess- walks_EPROCESS.VadRootand returns allocated VAD-backedMemoryBasicInformationranges sorted by base address.ReadMemoryRegionViaEprocess- resolves a single address against the VAD-backed region snapshot.- Internal
Win32NativeShared.ReadTebAddressViaThreadHandle- queries the live local OS forThreadBasicInformation.TebBaseAddressfrom an already-open thread handle. - Internal
Win32NativeShared.ReadTebAddressViaThreadId- opens a live local Windows thread by id, queries its TEB address, and closes the temporary handle. ReadPebAddressViaTeb- readsTEB.ProcessEnvironmentBlockfrom a caller-supplied TEB address and explicit target architecture.ReadProcessModulesViaPeb- reads loaded modules through a caller-supplied PEB address and explicit target architecture.ReadProcessModulesViaTeb- composes TEB-to-PEB reading with PEB loader-list walking.ReadProcessParametersViaPeb- reads command-line, image-path, current-directory, desktop/window metadata, and the environment pointer through a caller-supplied PEB address.ReadProcessParametersViaTeb- composes TEB-to-PEB reading withRTL_USER_PROCESS_PARAMETERSreading.ReadArchitectureViaEprocess- reads process architecture from kernel structure fields; this is the best path when the backend can read_EPROCESS.WoW64Process.ReadArchitectureViaTeb- reads process architecture from a TEB self pointer; this is the preferred user-mode path when a TEB address is known.ReadArchitectureViaPeb- reads architecture fromPEB.ImageBaseAddressand the in-memory PE machine type; use when only a PEB address is known.
Common Flows
-
Attach from selected window:
- pick or receive
IWindowHandle. - read expected PID from
ProcessId. - create reader by PID.
- validate
IsValidandProcessId.
- pick or receive
-
Read pointer chain:
- get
IMemoryAccessor. - call
ReadPointerChainorReadPointerChain32. - receive the final value of type
T; these methods do not return the final field address.
- get
-
Scan signature:
- create
BytePatternorStringPattern. - use pattern extension helpers.
- scope to module/region when possible.
- create
-
Find a code cave:
- create module-scoped memory with
MemoryOfModule(...). - call
EnumerateCodeCaves(minBytes, alignment)for executable caves. - pass
sectionFilterandacceptedFillByteswhen the cave is for data placement or when only a specific padding byte is acceptable. - for scalar state near injected code, use
Read<T>andWrite<T>; use byte-span writes only for machine-code payloads or encoded strings.
- create module-scoped memory with
-
Read entity list:
- create module-scoped
IMemory. - read entity-list pointer and entity count from known offsets.
- iterate entity pointers.
- wrap each address as a small memory object or immutable snapshot.
- display/log values and handle null or stale pointers.
- create module-scoped
-
Enumerate processes from kernel memory:
- use a backend that can read kernel virtual addresses, such as
KDProcessor a VMM/MPFS-backed reader. The memory source can be another machine, a dump, or a live VMM acquisition. - obtain a valid
_EPROCESSaddress from the backend/driver/acquisition. - call
ReadProcessesViaEprocess(eprocessAddress). - call
ReadProcessInformation(eprocessAddress)for a single process snapshot. - call
ReadPebAddressViaEprocess(eprocessAddress)when a later flow needs to start from the process PEB. - call
ReadProcessModulesViaEprocess(eprocessAddress)for module data when the backend can also read the target process user-mode address space. - call
ReadProcessParametersViaEprocess(eprocessAddress)for image path, command line, current directory, and related startup metadata. - call
ReadProcessThreadsViaEprocess(eprocessAddress)for thread metadata from the kernel thread list. - call
ReadMemoryRegionsViaEprocess(eprocessAddress)orReadMemoryRegionViaEprocess(eprocessAddress, address)for allocated VAD-backed ranges. These helpers intentionally do not synthesize free address-space holes or split regions by per-page state. - call
ReadArchitectureViaEprocess(eprocessAddress)when architecture should be inferred from_EPROCESS.WoW64Process. - pass the source OS build when it differs from the current host; the current
implementation is still layout-sensitive until the PDB offset resolver
replaces hardcoded
_EPROCESS, PEB, and loader-list offsets.
- use a backend that can read kernel virtual addresses, such as
-
Enumerate modules from user-mode memory without OS snapshot APIs:
- use a backend that can read the target process address space.
- obtain a valid TEB or PEB address from the backend, thread metadata, or another trusted discovery path.
- for live local window/hook flows, resolve the owner thread id and call
ReadTebAddressViaThreadId; useReadTebAddressViaThreadHandlewhen a suitable thread handle is already open. - call
ReadPebAddressViaTeb(tebAddress, architecture)when starting from a TEB. - call
ReadArchitectureViaTeb(tebAddress)first when the architecture is unknown and a TEB address is trusted. - call
ReadArchitectureViaPeb(pebAddress)when the architecture is unknown and only a PEB address is trusted. - call
ReadProcessModulesViaPeb(pebAddress, architecture)orReadProcessModulesViaTeb(tebAddress, architecture)for module data. - call
ReadProcessParametersViaPeb(pebAddress, architecture)orReadProcessParametersViaTeb(tebAddress, architecture)for startup metadata such as image path, command line, and current directory. - pass the target layout architecture explicitly; this is especially important for WOW64 and acquired-memory scenarios.
-
Manual-map a DLL into a compatible target:
- require an
IProcessthat also implementsIProcessSupportsManualMapping. - compatible local backends include
LocalProcessandNativeLocalProcess. - optional package backends may opt in;
WHProcesssupports x64 GUI targets when its WH control prerequisites are available. - use
InjectDllViaManualMapping(...); the mapper relies onIProcessControlApi.ExecuteCode(...)for synchronous completion before it reads mapper return buffers or frees shellcode. - do not treat
CreateThread(...)as a waitable completion primitive; it is the async/fire-and-forget thread start surface.
- require an
Prefer
- Prefer
IProcessas target contract. - Prefer
LocalProcessfor ordinary local access. - Prefer
NativeLocalProcessfor native handle/permission tuning. - Prefer
KDProcessonly when driver access is expected. - Prefer
LCProcess/ILCProcessBuilderfor acquisition/VMM scenarios. - Prefer validating PID before write-capable tooling.
- Prefer explicit versioned layout structs for kernel/private structures:
declare logical fields as
[field: FieldOffset(...)]auto-properties, dispatch through a small typed interface, and use typed static offsets for list/link pointer arithmetic. - Prefer explicit target architecture when using TEB/PEB helpers. The memory source may not match the current process architecture.
- Prefer
ReadTebAddressViaThreadIdorReadTebAddressViaThreadHandlefor live local Windows user-mode flows where a thread id/handle is already known, then validate the result withReadArchitectureViaTeb. - Prefer
IMemoryAccessor.Read<T>andIMemoryAccessor.Write<T>for unmanaged scalar/struct values in process memory. Use byte arrays/spans for actual byte payloads such as machine code, strings, file/protocol layouts, or bulk buffers. - Prefer
MemoryOfModule(...).EnumerateCodeCaves(...)before writing local ad hoc code-cave scanners.
Avoid
- Avoid starting with KD/MPFS without environment need.
- Avoid assuming every backend supports allocation, APC, remote thread, synchronous execution, manual mapping, or module enumeration.
- Avoid building manual mapping directly on
CreateThread(...); useIProcessControlApi.ExecuteCode(...)or a backend that exposesIProcessSupportsManualMapping. - Avoid using
ReadProcessesViaEprocesson ordinary user-mode process memory; it expects kernel virtual addresses and matching Windows kernel layouts. - Avoid treating VAD-backed region enumeration as a byte-for-byte
VirtualQueryExreplacement. It reports allocated VAD ranges and does not enumerate free holes. - Avoid depending on raw
_EPROCESS, PEB, or loader-list snapshots from the public API. The shared helpers intentionally returnProcessInformation,ProcessModuleInformation,ProcessParametersInformation,ProcessThreadInformation,MemoryBasicInformation, andArchitecture; low-level readers can define their own structs when they need raw layout work. - Avoid inferring TEB or PEB layout from host bitness. Pass the layout architecture that matches the supplied TEB/PEB address.
- Avoid using thread-to-TEB OS query helpers for dumps, VMM/KD snapshots, or cross-machine memory sources. Those need backend-supplied thread metadata or kernel thread-list walking.
- Avoid string/reflection-based offset lookup for layouts that may ship through
obfuscation. Do not rely on
Marshal.OffsetOf<T>(nameof(...)), auto-property backing-field names, or member-name strings for pointer math in obfuscated assemblies; keep needed offsets as typed static members near matching[field: FieldOffset(...)]declarations. - Avoid writing a new scanner before checking pattern extensions.
- Avoid
BinaryPrimitives,MemoryMarshal, or manual byte packing as a thin wrapper around ordinary scalar process-memory reads/writes. Reserve those APIs for explicit byte-format work.
Research Anchors
IProcess,IProcessMemory,IMemoryAccessor,IMemoryBackend,IProcessControlApi,IProcessControlApi.ExecuteCode,IProcessSupportsManualMapping,LocalProcess,NativeLocalProcess,KDProcess,LCProcess,ILCProcessBuilder,ReadPointerChain,VirtualQuery,BytePattern,StringPattern,MemoryExtensionsForPatterns,ProcessPEExtensions,MemoryExtensionsForEprocess,MemoryExtensionsForTebPeb,ReadPebAddressViaTeb,ReadProcessModulesViaPeb,ReadProcessModulesViaTeb,ReadProcessParametersViaPeb,ReadProcessParametersViaTeb,ReadTebAddressViaThreadHandle,ReadTebAddressViaThreadId,ReadProcessesViaEprocess,ReadProcessInformation,ReadPebAddressViaEprocess,ReadProcessModulesViaEprocess,ReadProcessParametersViaEprocess,ReadProcessThreadsViaEprocess,ReadMemoryRegionsViaEprocess,ReadMemoryRegionViaEprocess,ReadArchitectureViaEprocess,ReadArchitectureViaTeb,ReadArchitectureViaPeb,MemoryExtensionsForCodeCaves,EnumerateCodeCaves,CodeCaveEntry,ModuleSectionEntry,MemoryOfModule,RemoteMemoryObject,ReadString.
Search Synonyms
- memory
- process memory
- process reader
- local process
- native process
- kernel driver
- KD process
- EPROCESS
- ActiveProcessLinks
- WoW64Process
- ReadArchitectureViaEprocess
- ReadArchitectureViaTeb
- ReadArchitectureViaPeb
- ReadTebAddressViaThreadHandle
- ReadTebAddressViaThreadId
- TebBaseAddress
- ThreadBasicInformation
- ReadProcessInformation
- ReadProcessesViaEprocess
- ReadPebAddressViaEprocess
- ReadProcessModulesViaEprocess
- ReadProcessParametersViaEprocess
- ReadProcessThreadsViaEprocess
- ReadMemoryRegionsViaEprocess
- ReadMemoryRegionViaEprocess
- ReadPebAddressViaTeb
- ReadProcessModulesViaPeb
- ReadProcessModulesViaTeb
- ReadProcessParametersViaPeb
- ReadProcessParametersViaTeb
- TEB
- PEB
- ProcessEnvironmentBlock
- RTL_USER_PROCESS_PARAMETERS
- process parameters
- command line
- PEB_LDR_DATA
- LDR_DATA_TABLE_ENTRY
- process list
- kernel process list
- thread list
- ThreadListHead
- ETHREAD
- CLIENT_ID
- VAD
- VadRoot
- MMVAD
- MMVAD_SHORT
- MemProcFS
- LeechCore
- pointer chain
- signature scan
- memory region
- module
- PE
- code cave
- entity list
- memory object
- remote memory object
- manual mapping
- ExecuteCode
- IProcessSupportsManualMapping
- radar
- player list
Related Maps
- pattern-scanning.md
- windows-subsystems/window-handles.md
- osd/selection.md
- reverse-engineering/reprocess.md
- recipes/bot-memory-entity-list-reader.md
Kernel and snapshot boundaries
At EyeAuras c8b2304, EPROCESS helpers select a curated x64 Windows layout using
osBuild; omission uses the controller OS build. For a dump or another machine,
pass the build of the memory source. The reader must resolve kernel virtual
addresses and, for modules/parameters, the target process user address space.
These helpers do not install a driver or switch address spaces for the caller.
TEB/PEB readers support explicit x86/x64 layouts; choose the layout of the supplied
address, including the chosen WOW64 view. EPROCESS architecture detection uses
WoW64Process, whereas TEB detection checks its self pointer. None of these
walks freezes the target: the returned lists are collected reads, not atomic
snapshots. Traversal limits stop runaway walks rather than returning a complete
list beyond the limit.
VAD enumeration returns sorted allocated ranges, without free holes or per-page
state. Its MemoryBasicInformation.State is set to Commit; it is not a live
VirtualQueryEx result proving every page is committed/resident. Backend-specific
control operations and native compatibility remain separate from these shared
readers. See the backend maps before selecting a provider.