Project memory

A terminal session ends and its context ends with it. Without memory, every new session starts by re-explaining the stack, the folder layout, the naming rules, and the three decisions you already argued through last week.

So FutureX writes them down. At the start of a run it reads futurex-memory.md from the repo root and puts it in front of the model. The agent opens the conversation already knowing what the project is, how it is laid out, what you named things, and what is still unfinished.

That is the whole mechanism. One file, loaded every run. It is written in exactly two places — futurex init creates it, futurex compact regenerates it — and edited by you in between. Nothing rewrites it silently while the agent works.

It lives at the root of your repo, next to package.json, and it has seven fixed headings in a fixed order. Here is what a fresh one looks like on a small web project.

# FutureX project memory

## Overview

acme-web — Next.js + Fastify + Drizzle. _(Edit to describe the project's purpose & goals.)_

## Stack

- Language: TypeScript
- Framework: Next.js
- Package manager: pnpm
- Tests: vitest

## Architecture map

- `apps/`
- `packages/`

## Key modules

- `apps/web/src/app/layout.tsx` — 6 exported symbols

## Conventions

- Server components by default. "use client" only for real interactivity.
- Every route handler gets a test.

## Decisions log

- 2026-03-04: Billing moved to usage-based tokens, not seats.

## Open tasks

- Retire the legacy uploads route.

What each heading holds

The first four are derived from your repo, so futurex compact rewrites them whenever it regenerates the file. Conventions and Open tasks are yours and are never overwritten. The Decisions log is the exception: compact keeps the twenty most recent entries and moves anything older into an archive file, leaving a pointer in its place.

OverviewRepo

What the project is. Starts from the detected stack — edit it to say what the project is for.

StackRepo

Language, framework, backend, ORM, package manager, test runner.

Architecture mapRepo

Top-level directories, so the agent knows where things live before it opens anything.

Key modulesRepo

The files with the most exported symbols. Run futurex index first to fill this one in.

ConventionsYou

Naming, structure, testing — the rules you would tell a new teammate on day one.

Decisions logYou

One line per decision, written as - YYYY-MM-DD: what you decided.

Open tasksYou

What is unfinished, so the next session starts where the last one stopped.

One command, run once per repo. It writes the skeleton above, with the derived sections filled in from what it can detect.

Re-running it is safe. If the file already exists, init leaves it alone — it will never clobber notes you wrote. Run futurex index first if you want the Key modules section populated from the symbol index; see Commands for both.

Memory that grows without limit stops being useful: it crowds out the actual task and costs you tokens on every run. So the file has a soft budget of roughly 7,000 tokens, measured with a simple characters-per-token estimate.

Above the budget, compact rewrites the file in place:

1. Regenerates Overview, Stack, Architecture map, and Key modules from the repo as it stands today — stale structure gets replaced, not appended to.
2. Keeps the twenty most recent entries of the Decisions log inline and moves the older ones to a dated file under .futurex/logs/, with a line in the file pointing at the archive.
3. Leaves Conventions and Open tasks exactly as you wrote them.

Nothing is deleted. The archive is a dated file in your repo you can open, and the memory file says where it went.

Sometimes you want an answer with no project baggage attached — a generic question, or a check that the agent is not being led by an old note. Add the flag and memory sits out that one run.

It is per-invocation, not a setting. The next command reads the file again as normal. Pair it with --no-repo or --no-context when you want the model working from the prompt alone.

Memory being a plain Markdown file in your repo is the point, not an implementation shortcut. It means you can:

• Read it. Open it in your editor and see, in full, what the agent believes about this project.
• Correct it. A wrong line is a text edit, not a support ticket.
• Commit it. Check it in and your whole team shares one memory, reviewed in pull requests like any other file.
• Diff it. Every change to what the agent knows shows up in git diff.
• Delete it. Remove the file and the agent forgets. Run futurex init to start clean.

Memory you can audit is worth more than memory you cannot see.

The honest boundaries, so nothing here surprises you later.

• It does not sync itself. The file travels with your repo. If you want it on another machine, commit and pull like any other file.
• It is not encrypted. It is plain text on disk. Treat it like source code: no keys, no tokens, no customer data.
• It does not cross repos. One repo, one memory file. A second project starts with a blank one.
• It is not a transcript. It holds durable facts, not chat history. To pick a conversation back up, use futurex resume.