A project should remember more than a chat

Here is a perfect recipe for wasting your tokens:

1. Pick your %AI_PROVIDER_NAME%
2. Spend a long time explaining how the project works
3. Make decisions together
4. Close the session
5. Go back to step one
6. …
7. Bon appétit!

A new session, as we all know, is best served with cold context. That’s roughly how I worked when I first started using coding agents.

Open the project, start a conversation. No special context files, MCP, skills, or other infrastructure. Everything was simple and worked perfectly within one session: the agent knew what we had discussed, which decisions we had made, and why some hypothetical A had to be used to get B.

Cut. New context. Now you explain it all again: use A to get B, don’t touch this folder, we’ve already tried that approach, don’t do it again.

That’s how I learned one simple thing about agents: every new one is a little like the protagonist of Memento.

Ingredient #1. Instruction files

The internet says you need context and instructions. Fine. Let’s put AGENTS.md and CLAUDE.md in the project root.

Now a new agent could at least read the notes left by the previous one. Better. I asked agents to add useful facts about the project: which commands to use, which conventions to follow, where not to go, and why A still turns into B.

The setup seemed as reliable as a Swiss Army knife. It had one fatal flaw: it wasn’t invented here the instruction file collected more context with every session and eventually became a cross between a constitution and a shopping list. At some point agents started skipping individual items, so I had to move the important details closer to the top.

It became clear that context needed to be split into at least two kinds of information.

The first changes rarely: what the project is, which tools to use, how to build it, which rules must not be broken, and which ones can be ignored.

The second changes constantly: what we are doing now, what we have already done, where we are stuck, and what remains to be checked.

Ingredient #2. TODO.md

If AGENTS.md answers “how to work,” we need another file to answer “what to do.” That is how TODO.md files started appearing in my projects.

Great: agents add tasks, check boxes, and cross out lines. Everything is neat and obvious.

As the projects grew more complex, dependencies and plans from previous sessions started appearing in TODO.md. A checkmark showed that an item was done, but not how it was done. At some point the task list became a dumping ground.

Ingredient #3. Even more Markdown

Decomposition is the logical next step once your TODO.md turns into an encyclopedia. In my case, a docs folder appeared. Agents put plans, research results, and other useful knowledge there: the kind you don’t want to lose after closing yet another session.

Everything finally fell into place. But then another question appeared: should everything the agent put in docsreally end up in Git? Working documentation may contain sensitive information. Not necessarily a secret (you don’t keep secrets in version control, right?), sometimes just information that doesn’t belong in a shared repository. I didn’t want to audit the agent before every git add.

So context had to be prepared “in another kitchen.”

Ingredient #4. A folder next to a folder

Here is another recipe for keeping your project clean and fresh:

1. Create a <project_name>-context folder next to your project
2. Move AGENTS.md and the docs folder into it
3. Run the agent from that folder
4. You are magnificent

The result is a low-calorie dish: source code in one folder, plans, tasks, and little secrets in another.

But this setup has a flaw too: now you need to keep two projects open to work on one! Repositories started accumulating their smaller siblings context twins next to them.

One day I collected all of it in one large ~/context folder. The mess was organized now. I wasn’t. And it was still a mess.

Add a pinch of indexing

At some point I noticed that every new session started the same way: the agent would grab grep and begin getting to know the codebase.grep is a great tool. But watching agents discover the project structure from scratch every time (and marvel at it) was depressing.

“Maybe I should give the comrades some kind of index,” I thought.

Code search joined the list of requirements. Then a dependency graph. I realized I needed an off-the-shelf tool.

Ready-made dishes

I tried different task trackers, indexing systems, and graph tools. The open-source world has plenty of good solutions. There will be no section here called “everyone did it wrong, so I did it right.” They simply solved a different problem or expected a different workflow.

Three things kept getting in the way:

1. I didn’t want to maintain a zoo of separate tools: a task tracker, an index, and a graph
2. Some products were built around a UI I didn’t want to open
3. Some tools created their own files inside the project. That ingredient had already been in my dish :)

I needed a simple Soviet local tool that would bring everything together and expose it through a CLI for me and an MCP interface for the agent.

Istok

I imagine a story like this should go: “I had no choice left.” In reality, I had a choice. I could keep living with the folders, or I could use the existing tools.

But I like making things for myself, and it seemed that I’d found a real problem. A good excuse to build something.

That’s how Istok came to be.

It’s a local CLI and MCP server for keeping a project’s working state outside an agent session and outside the repository. Tasks, context, work history, and validation results live in SQLite. Repository indexes are stored separately, with Bleve used for lexical search.

Through the CLI, I can see open tasks and history right in the terminal. Through MCP, the agent receives the same context, sees the current task, records progress, and leaves results for the next session.

The project is open source.

For me, this is the main change. I no longer need to remember where <project_name>-context lives, open a second folder, or keep an eye on a pile of Markdown files. I can see the tasks in my terminal, while the agent gets structured context through MCP.

Not exactly impressive landing page copy, so here is a joke:

What is as big as a house, burns 20 liters of fuel per hour, smokes like crazy, and cuts apples into three pieces?

A Soviet machine designed to cut apples into four pieces!

The not-so-secret ingredient

Istok isn’t magic. It doesn’t promise to save tokens. Maybe the index and more focused context affect token usage, but I’m building the product around a simpler goal: I want to spend less of my attention keeping agents up to speed.

Istok is still far from perfect. For example, it currently has no mechanism for syncing context between devices. It is on the roadmap, but today every installation keeps its own local state.

And I think that’s fine. I’m building a tool around a real workflow and adding what that workflow actually lacks.

The result

I haven’t stopped using Markdown.AGENTS.md and CLAUDE.md are still great for stable instructions. The problems started when I tried to use the same files as a database, a task tracker, a work log, and a way to pass state between agents.

Sessions end. Tasks don’t have to. Agents change. Decisions remain.

That memory belongs to the project, not the chat.