Agent sessions and the memory layer

VENETA works in three parts: VENETA WorldModel (the industrial world model whose telecom, retail, semiconductor, grid, bank and supply-chain editions share one repository), VENETA Orchestrate (the data platform to come), and project veneta. WorldModel and Orchestrate each have several developers, and each developer runs several agent sessions. project veneta is built by two people (Hyunjoo Lee and Minjun Lee) together with their agent sessions.

project veneta takes the memory and self-improvement layer out of the VENETA WorldModel core and makes it usable on its own, for individuals and companies. The point is to make a local LLM more useful, and we expect there are people who want exactly that. It is entirely free and collects no telemetry. The site, the app and the open-source repository live apart from the WorldModel repository.

Three product lines, three development teams and dozens of agent sessions move at once, so the first problem was keeping one session’s hands off the files another session was editing. The answer had two parts: a development environment that gives every session its own git worktree, and a memory layer that keeps what a session learned after the session is gone. What follows is the record of two weeks with ten workspaces and ten worktrees.

A folder per session

A worktree-based agent development environment checks one repository out into a separate folder (worktree) per session and keeps each session inside its own folder. We use Orca ADE (onorca.dev); any tool built on the same principle will do. Two files in the repository say what is shared and what is copied.

Shared folders — large, rebuildable folders are shared from the main checkout as symbolic links. We share only node_modules and the Python virtual environment.
Per-session copies — files git does not track but every session needs its own copy of. For us, two .env.local files. Secrets never leave the machine.
Every other gitignored artifact (the framework’s build cache, SQLite databases) is created per session. Deliberately not shared.

The layout is simple. One WorldModel repository holds the core and one worktree per edition, plus worktrees pinned to specific commits for the paper. The site, the app and the open-source repository are one workspace each. Every session gets its own dev-server port; services that only need to run once are shared by all sessions.

What a session learned stays

Separate folders end the collisions, but sessions know nothing of each other. The mistake yesterday’s session fixed, the exception an operator pointed out, last week’s decision: today’s session had to be told again from the start. So we put veneta’s memory and self-improvement layer under the sessions. A rule a session learns arrives as a proposal, only what a person approves stays, and approved rules and past decisions carry over to the next session as they are. Who approved what is in the ledger. The two together were much better than folder isolation alone: the re-explaining fell away as the number of sessions grew, and a reversible record remained.

What worked

Sessions do not step on each other. Ten sessions committed to the same repository for two weeks; the merge conflicts were about the work, never about the environment.
A new session is cheap. No reinstall of node_modules, so a worktree takes seconds. The full test suite, about 1,500 tests, runs in 11 seconds from any session.
A paper snapshot can be pinned as a session. Put a worktree on one commit and measure only there; development in the other sessions never leaks into the measurement.
Sessions hand work to each other. The core session asks the site session to re-render from a commit; the site session reports the deploy back. That only makes sense when the folders are separate and what they learned is shared.

What bit us

The committed symlink. Because shared folders appear as links, git add -A in one session can commit the link itself. On September 19 a demo checkout received such a link and broke. Rule: before a merge, git ls-files -s | grep ^120000 lists link-mode files.
One dev server per session, on its own port. Two dev servers over the same build cache break each other. So the build cache left the shared list, and the preview-server config lives in the main checkout with each session’s path and port written down.
npm ci in one session touches every session’s server, because the folder is shared. After an install, restart the dev servers that were running.
Databases are per session, so “the same data” is not. A test incident inserted in one session does not break another session’s tests, but what was visible over there is absent here. Every measurement says whose database it came from.
The temptation to share more. Sharing caches and build output looks faster; the build-cache accident above is the answer. Share only what is rebuildable and never written to.

Who it is for

A team with more than one agent session on one repository gets its money’s worth at once; with a single session an ordinary checkout is enough. In short, worktree isolation hands out the folders, and the memory layer connects what the separated sessions learn. How ports, databases and servers are laid out per session is the team’s rule; ours is the four lines above.

Related notes: DGX Spark operations · Choosing a local writer