GhostPaw

Your agent keeps its state in markdown files.

MEMORY.md, TODO.md, USER.md, SOUL.md. They grow every session, nobody prunes them, and one wrong line steers every run after it.

GhostPaw is seven small Node.js libraries that file that state as records you can read and delete. Most of them are a few SQLite tables inside your agent's own process.

Find the file you outgrew Read all seven on GitHub

Free, MIT licence, Node.js 24 or newer. All seven have zero runtime dependencies. No account and no service to run.

A wolf head in profile drawn in thin cyan light lines, dissolving into violet sparks on black.

0runtime dependenciesin all seven packages

Which file is your agent outgrowing?

Pick the file. Its pane shows the package that takes it over, what one record holds and what we measured.

Replaces MEMORY.md

Beliefs instead of a memory file

@ghostpaw/codex version 0.3.0

Every remembered line becomes a belief with a source, a certainty and a history. Flags for stale, fading and low-trust beliefs are computed each time you read, so the junk drawer shows you what to prune. Since 0.3.0 it also ships an MCP server and a ghostpaw-codex command line tool.

One record holds

  • claim
  • source: explicit, observed or inferred
  • certainty and evidence count
  • freshness
  • lineage of corrections
Runtime dependencies
0
Tests
378
Size, gzip
32.5 KB
Import time
4 ms

codex source on GitHubcodex on npmcodex live demoRead how codex handles a wrong fact

Replaces TODO.md

Quests instead of a to-do list

@ghostpaw/questlog version 0.5.1

Work becomes quests with deadlines, repeats and unlocks. A quest only finishes with a written outcome, and a blocked quest stays blocked until the one before it succeeds.

One record holds

  • title and objective
  • dueAt or a scheduled window
  • unlocks that block other quests
  • outcome text on finish
  • repeat rule (RRULE)
Runtime dependencies
0
Tests
326
Size, gzip
42.6 KB
Import time
4.4 ms

questlog source on GitHubquestlog on npmquestlog live demoRead how questlog handles a hollow done

Replaces USER.md

Contacts instead of a user note

@ghostpaw/affinity version 0.2.4

The people, companies and services your agent deals with become contacts with identities, relationship tracks and a journal of evidence, plus the yearly dates that matter.

One record holds

  • contact and identities (email, phone, account)
  • social link: rank, trust, cadence
  • ties such as works_at
  • journal entries as evidence
  • date anchors such as birthdays
Runtime dependencies
0
Tests
436
Size, gzip
57.4 KB
Import time
5.8 ms

affinity source on GitHubaffinity on npmaffinity live demo

Replaces SOUL.md

An identity that changes with evidence

@ghostpaw/souls version 0.2.3

The agent's character is stored as a short essence plus traits that each carry evidence. Refinements are gated, consolidated at level-up and can be rolled back.

One record holds

  • essence
  • traits with evidence
  • level-up consolidation
  • full rollback
Runtime dependencies
0
Tests
510
Size, gzip
32.2 KB
Import time
3.9 ms

souls source on GitHubsouls on npmsouls live demo

Replaces skills/

Procedures that get better and keep their history

@ghostpaw/grimoire version 0.2.15

Each learned procedure stays a SKILL.md file. Git commits mark verified improvements, notes collect evidence, and a health check names stale, dormant and oversized skills.

One record holds

  • spell: a SKILL.md file
  • seal: a git commit per verified improvement
  • tier from seal count
  • notes awaiting distillation
  • catalogue health snapshot
Runtime dependencies
0
Tests
848
Size, gzip
47.5 KB
Import time
8.8 ms

grimoire source on GitHubgrimoire on npmgrimoire live demo

Replaces inbox/

A mailbox the agent can search offline

@ghostpaw/email version 0.3.0

IMAP sync and SMTP send with a local SQLite cache, threads built from References headers and full-text search. Ships an email command line tool.

One record holds

  • account with IMAP and SMTP config
  • folder with sync state
  • message headers, flags, labels
  • body and attachments
  • thread tree
Runtime dependencies
0
Tests
528
Size, gzip
48.7 KB
Import time
11.7 ms

email source on GitHubemail on npm

Replaces chat log

Every Telegram update kept before your handler runs

@ghostpaw/telegram version 0.5.0

A Telegram bot channel that mirrors each incoming update into SQLite first, files included, with full-text search and markdown rendering. Since 0.5.0 it talks to the Bot API with built-in fetch and has no runtime dependencies.

One record holds

  • message mirror
  • file bytes stored as BLOBs
  • FTS5 search
  • markdown rendering
Runtime dependencies
0
Tests
860
Size, gzip
34.5 KB
Import time
10.4 ms

telegram source on GitHubtelegram on npm

Measured 2026-10-24 on the maintainer's machine with Node.js 24.14.0 against the version shown: tests from node --test, size as gzip -9 of dist/index.js, import time with performance.now().

Where a markdown file stops working

  1. The junk drawer

    MEMORY.md grows every session and nobody prunes it. Developers say they pay tokens on every turn to reread lines that stopped being true.

    Instead: codex flags stale, fading and low-trust beliefs when you read them and recalls only active ones. Pruning becomes a list you can work through.

  2. The wrong fact

    One agent saves a wrong fact, and every other agent trusts it.

    Instead: In codex every belief records where it came from and how certain it is. A correction supersedes the old belief and keeps the lineage, so you can see what changed.

  3. Said it was done

    The agent reports the task finished. It is not.

    Instead: questlog will not finish a quest without a written outcome, and a blocked quest stays blocked until the one before it succeeds. An outcome is text, not a test, but it gives you something to check.

If memory makes you nervous

Plenty of developers switch agent memory off, because unread memories pile up and old lines win arguments. That is a fair worry. This is what GhostPaw does about it.

  • The database is a SQLite file your own process opens. You can read and delete every row with sqlite3.
  • A belief nobody confirms for 90 days is flagged stale.
  • Forgetting is one call: forgetBelief, or retire_belief to hard-delete.
  • Recall calls no model. It is full-text search plus local similarity over the active beliefs.
  • Each package is an import, not a framework. Take one and ignore the rest.

All seven, side by side

Four paw prints in light walking up and to the right, the oldest fading violet, the newest bright cyan.
The seven GhostPaw packages and what we measured
PackageTakes overVersionRuntime depsTestsgzipImport
@ghostpaw/codexMEMORY.md0.3.0037832.5 KB4 ms
@ghostpaw/questlogTODO.md0.5.1032642.6 KB4.4 ms
@ghostpaw/affinityUSER.md0.2.4043657.4 KB5.8 ms
@ghostpaw/soulsSOUL.md0.2.3051032.2 KB3.9 ms
@ghostpaw/grimoireskills/0.2.15084847.5 KB8.8 ms
@ghostpaw/emailinbox/0.3.0052848.7 KB11.7 ms
@ghostpaw/telegramchat log0.5.0086034.5 KB10.4 ms

Measured 2026-10-24 on the maintainer's machine with Node.js 24.14.0 against the version shown: tests from node --test, size as gzip -9 of dist/index.js, import time with performance.now().