Cloud agents start in a fresh sandbox every run: Claude Code on the web, Codex cloud tasks, CI jobs or your own containers. Nothing they learned last time is there. This recipe keeps their memory in Wiele as plain Markdown files: the sandbox fetches it when it starts and pushes each change, so the next run, on any machine, starts where the last one stopped.
There are two kinds of memory:
- Team memory, which every member's agents read and write: decisions, how-tos, facts about the product.
- Personal memory, which only one person's agents can see: that person's preferences, drafts and notes.
Setup
An owner or admin creates the workspaces. Only owners and admins can create workspaces.
Team memory is a public workspace with write access for every member:
wiele workspace create "Team memory" --visibility public --member-access write
Personal memory is a private workspace per person, shared with that person only. Owners and admins can still see it.
wiele workspace create "Anna memory" --slug anna-memory --visibility private
wiele access invite anna@example.com --path anna-memory:/ --role write
Anna accepts the invitation from the email, or with wiele org invitations accept INVITATION_ID. If Anna is already a member, accepting adds only the new access.
Seed the team memory with the rules every agent follows:
mkdir -p ~/Wiele/team-memory/facts
cp AGENTS.md ~/Wiele/team-memory/AGENTS.md
wiele track team-memory:/ ~/Wiele/team-memory
wiele push --directory ~/Wiele/team-memory -m "Memory rules"
Folder layout
team-memory:/
AGENTS.md rules every agent reads first
facts/
2026-10-02-billing-annual.md one fact or decision per file
2026-10-06-deploy-freeze.md
howto/
release.md
anna-memory:/
preferences.md how Anna wants work done
notes/
2026-10-07.md one file per day
One file per fact keeps parallel agents from editing the same file. Agents add files; they edit an existing one only to correct it.
A starting AGENTS.md:
# Team memory
Memory lives in ~/memory/team (everyone) and ~/memory/me (only you).
- Before you answer from memory, run `wiele pull --directory ~/memory/team`.
- To remember something, add a new file under facts/ named YYYY-MM-DD-topic.md.
Edit an existing file only to correct it.
- After every change, push with a short message:
`wiele push --directory ~/memory/team -m "MESSAGE"`.
- If the push fails with PUSH_CONFLICT, run `wiele pull --directory ~/memory/team --keep-local`,
merge your version with the recovery copy `wiele status` lists, and push again.
- Never put secrets, tokens or customer data in memory.
A session for each sandbox
Wiele has no service accounts or API keys yet. A sandbox signs in as the person its agent works for, with a session kept in a file. Sign in a separate session for each sandbox environment on your own machine, so you can revoke one without touching the others:
mkdir -m 700 ~/.wiele-sandbox
wiele login --credential-file ~/.wiele-sandbox/session.json
Store the content of session.json as a secret in the sandbox provider, for example as WIELE_SESSION. Don't paste it into a chat or a repository. Then delete your local copy, or keep it only to revoke the session later:
wiele auth logout --credential-file ~/.wiele-sandbox/session.json
A session lasts 7 days from its last use, so a sandbox that runs at least weekly keeps working. After a longer pause, sign in again and update the secret.
The agent can read and change what that person can. To give a team agent less access than a person, invite a separate account, such as agents@example.com, with access to team-memory only. That account counts as a member on your plan.
Fetch on start
Add this to the sandbox's setup script. It installs the CLI, writes the session file with owner-only permissions and fetches both memories:
npm install -g wiele
mkdir -m 700 -p ~/.wiele
printf '%s' "$WIELE_SESSION" > ~/.wiele/session.json
chmod 600 ~/.wiele/session.json
wiele org use acme --credential-file ~/.wiele/session.json
wiele fetch team-memory:/ ~/memory/team --credential-file ~/.wiele/session.json
wiele fetch anna-memory:/ ~/memory/me --credential-file ~/.wiele/session.json
The sandbox needs Node 24.20 or newer. Each command needs --credential-file; add it to the commands in AGENTS.md as well. A fetch downloads only the files under that folder, without history.
For a sandbox that runs for hours, have it pick up other agents' changes as they land:
wiele sync enable --directory ~/memory/team --credential-file ~/.wiele/session.json
Push on change
The agent pushes after each change, as AGENTS.md says. Each push is one revision, made with the session of the person the sandbox signs in as. A push that finds nothing to upload says so and creates nothing, so pushing at the end of every task is safe:
wiele push --directory ~/memory/team -m "Release freeze until Monday" --credential-file ~/.wiele/session.json
Anything not pushed when the sandbox stops is lost. Put a final push in the sandbox's teardown step if the provider has one.
Parallel agents
Ten sandboxes can push to the same memory at once. Wiele applies pushes that touch different files, so agents that add one file per fact never block each other. When two agents change the same file, the second push fails with PUSH_CONFLICT and publishes nothing; the agent pulls with --keep-local, merges the two versions and pushes again. HEAD_MOVED means another push landed during this one: pull and push again. See Conflicts and merging.
For a large rewrite, such as an agent reorganizing all of howto/, give it its own copy in a separate folder and review the result before it reaches main:
wiele copy create howto-cleanup --workspace team-memory --credential-file ~/.wiele/session.json
wiele fetch team-memory:/ ~/memory/howto-cleanup --copy howto-cleanup --credential-file ~/.wiele/session.json
The agent works and pushes in ~/memory/howto-cleanup. A person compares it with wiele copy compare howto-cleanup --to main --workspace team-memory and merges it. See Conflicts and merging.
Working with the agent
"Remember that we invoice annual plans in advance."
wiele pull --directory ~/memory/team --credential-file ~/.wiele/session.json
# writes facts/2026-10-07-annual-invoicing.md
wiele push --directory ~/memory/team -m "Annual plans are invoiced in advance" --credential-file ~/.wiele/session.json
"What did we decide about the deploy freeze?"
The agent pulls, then searches ~/memory/team with rg freeze and answers from facts/2026-10-06-deploy-freeze.md.
"Keep my draft of the launch email in my memory, not the team's."
The agent saves it under ~/memory/me/notes/ and pushes ~/memory/me, which only Anna and the organization's owners and admins can read.
"When did the refunds fact change, and what did it say before?"
wiele stat team-memory:/facts/2026-09-30-refunds.md --credential-file ~/.wiele/session.json
wiele history RESOURCE_ID --workspace team-memory --credential-file ~/.wiele/session.json
wiele read team-memory:/facts/2026-09-30-refunds.md --revision SHA --credential-file ~/.wiele/session.json
History lists when each version was saved. It doesn't record which agent or person wrote it, so if that matters, have agents put their name in the file.