a memory server for ai agents

Memory,
mapped.

When your agent hits a context miss, pagefault loads the right page back in from configured backends — no context stuffing, no RAG ceremony, no ticket-driven retrieval service. Seven tools, four transports, one config file.

get started view on github
tools
7
transports
4
backends
5
auth modes
4
§ 01

The name is the spec.

In an operating system, a page fault fires the instant a process touches memory that isn't resident. The CPU raises an exception, the kernel's handler quietly fetches the right page from backing store, and execution resumes — invisible, precise, below the program's awareness. The whole beauty of the mechanism is the split-second of resolution: the gap between “I need this” and “here it is” closes without ceremony.

pagefault does the same for AI agents. When a model needs context it doesn't have, it faults to this server, which loads the right information from configured backends — files, search indices, spawned subagents — and hands it back. No stuffing the context window with everything a session might need. No elaborate retrieval pipeline to sit between agent and memory. Just the primitive, in the shape the metaphor promises.

  1. fault

    agent references a page that isn't in context — a file it hasn't seen, a memory it was never given.

  2. handler

    pagefault picks the right backend, applies filters + redaction, optionally spawns a subagent for deep retrieval, and runs the fetch on a detached goroutine that survives HTTP disconnects.

  3. resolved

    the agent receives the page and resumes execution. Every call is audited in JSONL for after-the-fact forensics.

§ 02

Seven tools. One surface.

Tool names follow a pf_* scheme borrowed from Unix memory management and kernel debugging — one verb per primitive, nothing cute. Every tool is exposed over MCP, REST, and the CLI with the same filter and audit semantics.

wire cli does unix analog
pf_maps maps list available contexts & their resources /proc/self/maps
pf_load load load a named, pre-composed context bundle mmap
pf_scan scan search across one or every backend grep -r
pf_peek peek read a single resource by memory:// uri cat
pf_fault fault spawn a subagent for deep retrieval, async-by-default page-fault handler
pf_ps ps list agents, or poll a task by task_id ps
pf_poke poke write back through the sandboxed append path write(2)

Seven tools, memorable names, clean namespace. See docs/api-doc.md for the full reference.

§ 03

Quick start.

From clone to first request in under a minute. The binary is a single Go file with no runtime dependencies.

  1. 01

    Build the binary.

    $ make build
$ ./bin/pagefault --version
pagefault 0.12.2
  2. 02

    Drive tools from the CLI — no server needed.

    $ ./bin/pagefault maps --config configs/minimal.yaml
$ ./bin/pagefault scan pagefault --config configs/minimal.yaml
$ ./bin/pagefault peek memory://README.md \
    --config configs/minimal.yaml
  3. 03

    Or run the server and hit it over HTTP.

    $ ./bin/pagefault serve --config configs/minimal.yaml
$ curl -s http://127.0.0.1:8444/health | jq
$ curl -s -X POST http://127.0.0.1:8444/api/pf_scan \
    -H 'Content-Type: application/json' \
    -d '{"query":"pagefault"}' | jq
  4. 04

    Wire it into Claude Code.

    $ claude mcp add pagefault \
    --transport http \
    --url https://pagefault.example.com/mcp \
    --header "Authorization: Bearer pf_your_token_here"

    Claude Desktop uses legacy SSE and the OAuth 2.1 authorization-code + PKCE flow out of the box — see README.md for the full walkthrough.

§ 04

Every transport your client speaks.

§ 05

Under the hood.

A single chi router, an auth middleware, a tool dispatcher, and a set of backends pluggable through YAML. The detached task manager runs every pf_fault spawn on a goroutine outside the caller's HTTP request, so proxy timeouts and client disconnects no longer kill long retrievals. 

 ┌────────────────────────────────────────────────────────────┐
 │  clients   claude code   ·   claude desktop   ·   curl     │
 └───┬──────────────┬───────────────┬──────────────────┬─────┘
     │ /mcp         │ /sse /message │ /api/pf_*        │ cli
     ▼              ▼               ▼                  ▼
 ┌────────────────────────────────────────────────────────────┐
 │  chi router · cors · ratelimit · recover · logger          │
 │  ┌──────────────────────────────────────────────────────┐  │
 │  │  auth    bearer · trusted_header · oauth2 · none     │  │
 │  └───────────────────────┬──────────────────────────────┘  │
 │                          ▼                                 │
 │  ┌──────────────────────────────────────────────────────┐  │
 │  │  tool dispatcher                                     │  │
 │  │    pf_maps  pf_load  pf_scan  pf_peek                │  │
 │  │    pf_fault ┄┄┄ async ┄┄┄ task manager               │  │
 │  │    pf_ps    pf_poke                                  │  │
 │  └──────┬───────────┬──────────────┬────────────────────┘  │
 │         ▼           ▼              ▼                       │
 │     filter       audit        backends                     │
 │   path / tag    jsonl    fs · subproc · http               │
 │   redaction              · subagent-cli · subagent-http    │
 └────────────────────────────────────────────────────────────┘

Full walkthrough in docs/architecture.md .

memory, mapped.

pagefault is a single-binary Go server. Point it at a directory, give it a token, and your agent has a memory it didn't have five minutes ago.

read the source