Give Your AI Agent Loop Memory With a Simple JSON File (No Database Required)

The problem

An agent loop that runs once and exits forgets everything the moment the process ends. That’s fine for a single request, but the moment you want “remind me what you already checked today” or “don’t repeat work you already did,” you need memory that survives between runs — and reaching straight for a database to solve that is more infrastructure than most small agents need.

Expected outcome

By the end of this guide you will have a working memory module that any script can call to remember something, recall recent entries, or clear everything — backed by one JSON file, no server and no setup.

Requirements and costs

• Node.js (version 18 or newer).
• Cost: free. No database, no API key, no network call.

Unfamiliar terms, explained

• Persistence — data that survives after the program that created it exits, as opposed to a variable that disappears the moment the process ends.
• State file — a plain file (here, JSON) used to store that persisted data, read back in on the next run.

Step-by-step implementation

1. Download the starter from the link below.
2. Open a terminal in that folder.
3. Record something:

   node agent-memory.js remember "checked the invoice total"

4. Record another entry, then read them back:

   node agent-memory.js remember "sent the follow-up email"
   node agent-memory.js recall

5. Clear memory when you want a fresh start:

   node agent-memory.js forget

6. Wire it into your own agent loop by requiring agent-memory.js and calling remember()/recall() directly from your code, at the point where your loop decides what to do next — for example, checking recall() before acting, to avoid repeating something already logged today.

A real example

$ node agent-memory.js remember "checked the invoice total"
{"ok":true,"total_entries":1}

$ node agent-memory.js remember "sent the follow-up email"
{"ok":true,"total_entries":2}

$ node agent-memory.js recall
{
  "ok": true,
  "entries": [
    { "at": "2026-10-05T03:43:07.356Z", "note": "checked the invoice total" },
    { "at": "2026-10-05T03:43:07.413Z", "note": "sent the follow-up email" }
  ]
}

$ node agent-memory.js forget
{"ok":true,"cleared":true}

Verification and troubleshooting

What we tested, on 5 October 2026 (record TNT-TEST-2026-10-05-002): two separate remember calls in two separate process runs, confirming the second run correctly saw the first run’s entry (proving it actually persists across runs, not just within one); a recall that returned both in the order they were added; and a forget that correctly emptied the file, confirmed by a following recall returning no entries.

Troubleshooting:

• “usage: node agent-memory.js…” and nothing happens. You need a command: remember "text", recall, or forget.
• Memory doesn’t seem to persist. Check you’re running the script from the same folder each time — memory.json is created next to the script, so running it from a different working directory with a copy of the script elsewhere creates a separate memory file.
• The file gets corrupted (rare, e.g. a crash mid-write). The loader already treats an unreadable file as empty memory rather than crashing, so the agent keeps working; you lose that session’s history, not the ability to run.

Limitations and alternatives

A single JSON file is not safe for two processes writing to it at the exact same time (one can overwrite the other’s save) and it is not efficient for tens of thousands of entries. For a single local agent running one task at a time, neither of those matters. Once you have multiple agents sharing memory, or need to search old entries by content rather than just reading recent ones, that’s the point to move to a real database — not before.

Free resources

The download contains the full memory module, ready to require from your own agent loop.

Download the agent memory starter (ZIP, 1 KB)

Is there a paid version?

Not yet. This is the complete method. TNT Review has sold nothing to date and has no checkout, so any price we discuss in future should be read as a hypothesis, not an offer.