context-infrastructure: a year of agent memory, published as a blueprint

A year of running, then published as a blueprint

The repository describes itself as the complete structure of a context infrastructure system that had been running for a year, and it says what it thinks that is worth. The main value is as a reference implementation, so that you can see what the system looks like, how the data flows, and how memory accumulates.

What it is not is a tool that works out of the box. The README says it is a blueprint you can refer to rather than a finished product, and that after cloning it you can immediately experience the difference between having context and not having it. It then says the part that matters most, which is that to make the AI genuinely yours, you have to collect your own behavioural data from the start, and there is no shortcut.

That framing is unusual and it is the reason the project is worth reading. A system that has been running for a year has a specific character: the rules are shaped by what actually happened, and the memory is a record rather than a design. Publishing it as a blueprint rather than a template is an admission that the accumulated content is the author's and not the reader's.

The system covers the four things the repository description lists, persistent memory, personal rules, skills and scheduled observations, and the project is Python, on the main branch, with the last push on 2026-10-22. The README states the licence as MIT, while the repository's own licence metadata carries no classification, so the README is the only statement of terms available.

Five minutes, three commands and one file

The quick start is short, and it is honest about what the short part is for.

git clone https://github.com/grapeot/context-infrastructure
cd context-infrastructure

Then the directory is opened with an agent tool, and the README names three: Claude Code, OpenCode or Cursor. There is no install step, no dependency file to resolve and no service to start, because the point of a context system is that it is a set of files the agent reads rather than a program that runs.

The one thing you have to do is open rules/USER.md and fill in your basic information, and the README calls this the highest return on investment step, saying that once it is done the agent's behaviour is immediately personalised. The detailed steps live in setup_guide.md.

So the first five minutes give you the layout, the templates and a working demonstration of what having context changes. The months of value come later, and they come from the data collection the README warns about. That split is the honest shape of this kind of project, and it is why the setup guide is a separate document rather than a section of the README.

There is also a bigger system described in docs/SKILL_ECOSYSTEM.md, for anyone who wants to extend this into a fuller working environment. That document lists a set of separately installable public skill repositories, covering web search, Google Docs, Google Maps, email and newsletters, OpenCode, PPTX, social media, payment analytics, home network analysis and a local process launcher. The design is that context-infrastructure stays lightweight, and the wider capabilities are installed on demand from independent repositories.

The directory layout is the architecture

The tree in the README is worth reading as a design document, because each directory answers a question.

At the root, AGENTS.md is described as the root routing table and the starting point for the AI in every session, with setup_guide.md for configuration and .env.example as the environment template.

The rules/ directory holds the persistent text the agent reads. There is SOUL.md, the agent's identity and behavioural tone, and USER.md, your preferences and background, both as templates, and COMMUNICATION.md, a communication style guide, which the README says most people can adopt directly. There is WORKSPACE.md as a directory routing index, and two subdirectories that are the accumulated content: axioms/ with 43 decision axioms, described as the presentation layer, and skills/ with 39 skill Markdown files, including migration pointers and not counted in the index.

The contexts/ directory holds what the system has written. There is memory/OBSERVATIONS.md, which holds the L1 and L2 layers of the three-layer memory system, and three storage directories for survey reports, daily records and thought reviews.

The periodic_jobs/ai_heartbeat/ directory is the code, with a docs/ subdirectory holding a PRD for the memory system and a knowledge base describing the procedure for observations and reflection, and a src/v0/ directory with the observer and reflector scripts.

Then there is tools/share_report/ for report publishing, described as Tier 2, and adhoc_jobs/ for on-demand tasks. The layout separates the instructions the agent reads, the data it has written, the code that writes it, and the work that happens once, and that separation is the architecture.

Three layers, and the rule about copying

The three-layer structure is the conceptual core of the project, and it comes with an explicit permission boundary.

The presentation layer is the one you can look at but not copy. The rules/axioms/ and rules/skills/ directories hold what the system accumulated over a year, with the 43 axioms distilled from concrete experiences and the skills summarised from real projects. The README says these represent the original author's point of view, that they are useful as a reference, and that they cannot replace the cognition you accumulate yourself.

The reusable layer is the one you use directly. SOUL.md and USER.md are templates you fill in, COMMUNICATION.md is a general communication style guide that most people can adopt as it stands, periodic_jobs/ai_heartbeat/ provides the implementation code for the memory system, and docs/CRONTAB.md covers the scheduled task configuration.

The non-reusable layer is the specific content of the axioms and the specific experience behind the skills. The instruction for those is to understand their structure and how they were formed, and then to accumulate from your own data.

That is a clean piece of thinking, and it is worth pausing on why it is right. An axiom copied from someone else is a rule you do not understand, and an agent that follows rules it does not understand will apply them badly when the situation is slightly different. The forty-three axioms are worth reading for their structure, which is what the README asks, and the minutes of observation that produced them are not transferable.

The memory system is two cron scripts

The implementation of the memory layer is small, and that is a design choice rather than an omission.

There is a daily observer script and a weekly reflector script, both under periodic_jobs/ai_heartbeat/src/v0/, and both need cron configured, which is what the docs/CRONTAB.md file is for, a scheduled task configuration guide with a timeline and an example crontab.

The design documents explain what they are supposed to do. The PRD is the memory system design document, and the knowledge base is the standard operating procedure for observations and reflection. The output lands in contexts/memory/OBSERVATIONS.md, which holds the L1 and L2 layers of the three-layer memory system, and the other contexts/ subdirectories are where the longer outputs go, survey reports, daily records and thought reviews.

So the loop is: the observer runs daily and writes down what happened, the reflector runs weekly and reviews, and the results feed the files the agent reads at the start of the next session. The three-layer memory system, of which OBSERVATIONS.md holds two layers, is the part the observer and reflector maintain.

The division of labour between the daily and the weekly job is worth noticing, because it is the difference between a system that accumulates and one that drowns in its own logs. And the whole thing is deliberately scheduled rather than triggered, which means the cost of running it is a cron entry and the risk of not running it is that the memory stops growing.

The environment file shows what the system actually touches

The .env.example is the most revealing file in the repository, because it lists every external system the memory system talks to.

There is a Gmail section, with a username, an app password and a list of recipients, used by the email sender and by the crontab monitor's alert emails. There is an OpenCode server URL, used by the observer, the reflector, the newsletter and the crontab monitor, which tells you the agent runtime is reached over HTTP rather than in process.

There is a Google Analytics 4 property identifier and a Google application credentials path, used by the metrics script, and a Kit or ConvertKit API key, used by the metrics script and by newsletter publishing. Then the Typefully variables, an API key and a social set id for posting, and for the metrics script an authorization, an account and a session that the comment says has to be scraped from the browser, which is a fragile dependency worth noticing.

The image generation section is longer than you would expect. There is a Gemini API key, optional Google compatible variables, and a set of per-task model overrides for a flash image model, a pro image model, a general image generation model and an upscaling model, plus an OpenAI image model, and an OpenAI API key at the end for the local embeddings used by the semantic search.

Two things follow from reading that list. The system is not a local program, it is a set of integrations with an agent server and with several third-party services, so it needs credentials and it has external failure modes. And the comment that the semantic search has been upgraded to a standalone public skill repo, and is no longer under tools/, is a sign of where the design is heading: the core stays small and the integrations move out.

Editorial conclusion

Adopt this repository as a template for an agent's context and memory layout if you are tired of re-explaining your preferences every session, because the routing file, the identity and user templates and the observation and reflection scripts give you a working structure in five minutes. Do not adopt the axioms or the skills as your own, because the README states plainly that they encode the original author's perspective and cannot replace what you accumulate yourself. Before you wire up the cron scripts, read the environment template, since the observer and reflector talk to an agent server and several third-party APIs, and remember that the semantic search part has already been moved out into its own repository, so the core you clone is the smaller half of the system.

Frequently asked questions

Official sources

1. grapeot/context-infrastructure on GitHub
2. Issues
3. README