How Developers Manage AI Agent Context Across Clients and Projects

Most developers in this Hacker News thread do not solve AI agent context with one universal memory product. They solve it with plain Markdown files kept close to the code, decision records, searchable session logs, and hard separation between clients at the filesystem or namespace level. The thread, an Ask HN post by Michel_Aventin with 29 comments, is a practical survey of what actually survives daily use across Claude Code, Codex, Gemini, and local models.

The dominant pattern is files in the repository, not a new database

The most common answer to "how do you give an agent context at the start of a session" is a project-level Markdown file that the agent reads first. AGENTS.md and CLAUDE.md are the canonical examples.

"This is what agents.md / claude.md is for, its the first file Claude Code and Codex read." — @giancarlostoro

Several commenters go further and keep the file deliberately small. @spike021 says they have moved away from a large AGENTS.md or CLAUDE.md and instead maintain one or more curated project Markdown files scoped to the current work, with references to specific modules, commands, and database schemas. The stated goal is to avoid giving the agent context it does not need.

@mceachen describes an even more minimal entry point: sometimes only a link, a Sentry ID, and a skill name. For nontrivial tasks, context is maintained in a "technical project plan" document that is kept up to date. The same commenter argues that the more slack an agent is given, the more likely a session's work will have to be discarded, and that reviewing the plan before implementation prevents sessions from going far off course.

Decision records and spec documents carry the decisions that agents forget

The second recurring pattern is to write down decisions in a durable, structured form rather than relying on chat history. The formats vary, but the function is the same: give the agent a place to look up why something was done.

@charlesabarnes keeps a gitignored Architecture Decision Record (ADR) directory in every repository, plus a gitignored status document for resuming where work left off. The commenter notes that no additional tooling is needed because the models usually understand the format natively.

@lp92 describes a heavier documentation regime: every feature and bug fix has a TDD, FDD, implementation plan, or root-cause analysis document in Markdown, grouped into logical subfolders, alongside a master system architecture and design document. A master index file lists every document with a brief overview. According to the commenter, that index is what cuts down scanning in a cold session.

"The index file really helps cut down the scanning done in a cold new session." — @lp92

@murillians points to spec-driven development tools such as OpenSpec, Git SDD Kit, and GitShipDone as a way to handle previous decisions and design context, noting that these live in the project repositories so they do not pollute each other.

Wikis and gatekeeper scripts enforce that context is actually written

A more elaborate pattern is a project wiki that the agent must update before it can finish a round of work. @mapontosevenths describes using "Karpathys LLM wiki with QMD" plus a small gatekeeper.py script that the agent must run to complete a round or begin a new one. The script records state, lints, and validates that the wiki has been updated with findings, lessons learned, and documentation. The agent cannot proceed until that is done. AGENTS.md then tells the agent to use QMD for semantic search of the wiki before starting significant work.

"It's expensive, in terms of tokens, but well worth it. I could reproduce any stage of my project if I wanted. I always know why they did what they did (if they do), and the agent's can't really forget anything important." — @mapontosevenths

The trade-off is explicit: this approach costs tokens, but it produces an auditable record of decisions and makes the project reproducible.

Session indexing and search tools fill the gap left by chat history

Several commenters built local tools that index past sessions so an agent can search them. The shared idea is that chat transcripts already contain the decisions, but no vendor exposes them in a searchable, cross-provider form.

• @matthewslotkin built a tool that locally indexes all past sessions for search and continuously builds and maintains a wiki.
• @hyldmo built Farero, which stores every chat regardless of AI provider in an indexed SQLite database on a Mac and injects MCP tools plus a small prompt into Codex, Claude, and OpenCode so the agent can search every decision and chat.
• @anyonecancode built a localhost tool using SQLite for metadata and the XDG directory convention for content. It organizes work into topics, each with tickets, artifacts, and Claude Code sessions. A running topic.md is updated at the end of each session, and compaction periodically moves full content to an archive to keep working context small.
• @synapsomorphy runs Claude and Codex from the same localhost web server, stores chat logs as JSONL in a never-pushed git branch per project, and runs agents in Podman containers.

Client isolation is usually enforced by the filesystem or by namespaces

For consultants and agencies, the critical requirement is that one client's context never leaks into another's. The simplest answer in the thread is to separate operating-system identities.

"If you have separate clients, I would use a different username/login for each client so session transcripts (like in ~/.claude/... are segregated." — @mceachen

@MadBrad-Develop keeps client context separate in different directories. @cpinto built Estratos specifically to enforce isolation, using a layered namespace such as root.agent_name.client-a.project-a1. Instructions are concatenated from root, agent, client, and project layers, and the system prevents the model from even knowing that a sibling client subtree exists. The commenter says this targets accounting firms, where sharing context between clients is unacceptable.

Multi-agent work needs a shared ledger and a commit-sized unit of progress

Developers who run more than one agent type generally do not try to sync full conversational state between them. They synchronize through files, commits, or a shared database.

@MadBrad-Develop built a database modeled on IBM 1401 punchcards, with a wake phrase exposed through the IDE's MCP, so state is held in a few hundred tokens. Multiple agents read and write the same database, which allows switching between agents depending on the task.

@akst tells multiple agents to maintain write-only ledgers to coordinate and avoid overlapping work, and argues this is easier when the project is split into self-contained components with communication boundaries defined in protobuf.

@synapsomorphy offers a sharper rule:

"The minimal delta is a commit. Every implementation turn must end with one or multiple, and a clean worktree." — @synapsomorphy

The same commenter recommends short, commit-linked chats to avoid expensive cache writes, and tracking lines of code over time as a signal for when to use stronger models.

Failures are usually caught quickly, but the risk grows with agent autonomy

The thread's failure reports are modest in cost but consistent in shape: the agent claims completion, and a human check finds the work is not actually correct.

@MadBrad-Develop reports an agent saying a task was complete and verified when it was not working as planned. After the developer suggested a possible reason, the agent fixed it on the next run. The cost was about seven minutes. The commenter attributes the low cost to keeping an eye on everything the agents do.

@mceachen frames the larger risk: more slack given to an agent means a higher chance that a session's work has to be discarded. Reviewing a technical project plan before implementation is presented as the mitigation.

Build versus buy: many built their own, and at least one says don't

The thread contains a clear split between developers who built custom harnesses and one who argues the problem is already solved.

@jwilliams strongly encourages building something, but frames the real problem as managing the developer's own attention and mental load rather than storing text. The recommendation is to build a tool that fits one person's workflow, expect it to be disposable, and be ready to abandon it when better tools appear.

@jen729w, the creator of the Johnny.Decimal numbering system, argues the opposite:

"I really wouldn't [build something]. I get 10 emails a week from people who already are and I don't see the point. It's a solved problem." — @jen729w

The proposed solution is carefully named Markdown files and folders, each with a stable ID, an index entry in an Obsidian vault, and a corresponding folder on disk. Launching an agent in the same folder for a given piece of work gives it both the human-readable shared memory and its own session transcripts, with --resume available for past conversations. The commenter says setup takes about half an hour and can be done for free.

The practical baseline

The thread converges on a small set of practices that can be adopted without buying anything:

1. Put a short, curated context file in each repository and keep it scoped to the current work.
2. Record decisions in ADRs, specs, or a running project document rather than relying on chat history.
3. Maintain an index of documents so a cold session does not have to scan everything.
4. Separate clients at the operating-system or namespace level, not just by prompt instruction.
5. For multi-agent work, coordinate through commits, ledgers, or a shared database rather than trying to merge conversations.
6. Review plans before implementation, because the cost of a bad session rises with the autonomy granted to the agent.