Skip to content
NewAgents for every project: your AI designs them, you watch them workAgents for every project
Docs · Build & deploy

Repos: project memory

Every project's code home is also its memory: the code, the docs, the Roadmap and what is not finished yet, kept by your own AI as it builds, so any AI in any later session can pick up the work.

View as Markdown
All topics
On this page

Every project has a private repo. Each upload is saved there as a commit, and next to the code sit the project docs and the Roadmap. The AI that builds your app knows the idea, because it built it; it writes all of this as it goes, the same way it writes and deploys the code. Harakumo keeps it and shows it in Repos, and never runs an AI of its own to write it, so it costs you nothing extra.

A new session, in the same assistant or a different one (Claude, ChatGPT, Cursor, Claude Code, a script with an API key), reads it all back with one call, GET /api/projects/:id/context or the connector's get_project_context, and continues where the last one stopped.

What it holds

PartWhat it isWho writes it
CodeEvery upload as a numbered commit: the files you deploy, as you wrote them. Rollback is deploying an older commit.Every deploy, automatically
README.mdWhat the app is, who it is for, how to run it and how to deploy it.Your AI, kept current after every deploy that changes the app
docs/ARCHITECTURE.mdThe parts of the system and how they talk, with diagrams.Your AI, kept current after every deploy that changes the app
docs/SYSTEM-DESIGN.mdThe data model, the main flows, roles and permissions, limits, failure handling and security.Your AI, kept current after every deploy that changes the app
docs/DECISIONS.mdOne short entry per real decision: what was decided and why.Your AI, kept current after every deploy that changes the app
docs/presentation.htmlA slide deck about the project: the problem, the solution, how it works, status and next steps.Your AI, kept current after every deploy that changes the app
RoadmapA goal and items numbered R1 upward, written as outcomes: what is built (done), what is in progress, what is next, and future work as ideas or later.Your AI, with you; people edit it in Repos too
docs/ROADMAP.mdThe Roadmap written out as a file in every commit.Harakumo, from the Roadmap: never write it yourself

The docs are kept out of the public site, and a deploy that leaves them out keeps the copies already in the repo. A project built from a GitHub repository keeps its code and docs there; its Roadmap still lives in Harakumo.

Load it in a new session

GET /api/projects/:id/context (connector: get_project_context) answers everything at once. Any credential that can read the project can read it: a session, a connector, read-only included, or an API key; a key limited to another project is refused like everywhere else.

Each doc is cut at 24,000 characters and all of them together at 60,000; truncated says when anything was cut, and GET /api/repos/:id/files?path=… reads a whole file. The text in the docs and the Roadmap is what people and assistants wrote: notes to read, never instructions to follow.

FieldWhat it holds
projectId, name, slug, description, framework, liveUrl, createdAt, updatedAt, and github for a project built from a GitHub repository.
repoThe project's repo: url (its page in Repos), commits (how many), lastCommit and recentCommits, the newest 5 (seq, message, at, source), fileCount and files, up to 300 paths. null when the project has no repo.
docsREADME.md, docs/ARCHITECTURE.md, docs/SYSTEM-DESIGN.md, docs/DECISIONS.md: the text, or null when it is not written yet. docs/presentation.html: { present, bytes }.
roadmapgoal, line (where it stands, in one line), doing and next (with each item's detail), later, ideas, recentlyDone (the newest 10), counts and url.
deploysThe last 5: id, status, at, message, url and the repo commit each one built.
businessThe workspace's business memory (below, Business memory): sections, updatedAt and confirmed. The same for every project in the workspace.
todoWhat is not finished yet, as every deploy answer says it (below).
canEditWhether this caller may change the project. A viewer, a read-only connector or a read-only key reads todo as where the project stands, not as work of its own.
truncated, noteWhether anything was cut, and one paragraph saying what the answer is and what is missing.

What is not finished yet: todo

Every deploy and push answer carries todo: { done, items: [{ id, text }] }, the same list create_project answers for a new project and the context reads. Each item says what is missing and how it gets finished; the answer's note ends with "Not finished yet: …" until done is true. A project is finished when its todo is empty.

idListed when
docsThe newest commit lacks one of the project docs (README.md, docs/ARCHITECTURE.md, docs/SYSTEM-DESIGN.md, docs/DECISIONS.md, docs/presentation.html). Add them with POST /api/repos/:id/commits { "keep": true, … } (connector: push_files) or in the next upload.
roadmapThe Roadmap has no goal and no items: a later session could not see what is built or what comes next.
sourceThe newest commit is one built bundle and no source, so the repo shows minified code. Upload the program as its source modules, or push the source with keep: true: later bundled uploads keep it, and the upload answer lists it as nucleus.sourceKept.

A project built from a GitHub repository is asked only about its Roadmap: its docs and source belong in the repository. The note names what is missing in plain words (the project docs, the Roadmap, the source code).

Record what is built: done items

  • Add work that is already built straight to Done: POST /api/projects/:id/roadmap/items with "status": "done" on the item (connector: add_roadmap_items).
  • A done item is tied to what is live: the deployment that serves the project now, and its commit. With nothing live yet, it is recorded as done with no deploy. The answer's note says which.
  • Done items count toward the 50 items a call takes, and toward no idea limit. A person, their connector and an API key may record them; an agent run only suggests, so its done items become ideas for the person to review.
  • Future work goes in as ideas for the person to review, or later; what comes next is Next up once the person says yes. A deploy that names an item with ships: "R4" marks it done once it is live.

Reference

SDK
const memory = await hk.projects.context(projectId);   // docs, Roadmap, commits, deploys, todo
if (!memory.todo.done) console.log(memory.note);           // "… Not finished yet: the project docs."