Load Agent Memory

Load selected memory files into a sandbox from one exact version, then save changes without losing another update or exposing a private key.

Code Storage enables agent memory with exact reads, safe concurrent changes, and a history that can be inspected and reverted.

​

Choose the repository and exact version

Use a separate memory repository when the information needs its own access rules, storage lifetime, or delete boundary. You can use one repository per project, user, tenant, or company.

Before the agent reads memory, read the current commit SHA of the branch and store it with the agent session. This SHA is the pinned revision. It always identifies the same files, so the agent reads one exact version.

TypeScript

import { Pierre } from '@pierre/sdk';

const pierre = new Pierre(); // reads PIERRE_ORG and PIERRE_PRIVATE_KEY
const memoryRepo = 'acme/agent-memory';

const history = await pierre.repos.commits.list({ repo_name: memoryRepo, ref: 'main', limit: 1 });
const pinnedRevision = history.data[0].sha;

Use repos.tags.create when a person needs a readable name for the version.

​

Load only the required files

Give the sandbox a temporary API token for only the memory repository. Keep the organization private key in trusted product code. See Authentication for token details.

Use repos.archive.get with file patterns to fetch a group of memory files without a git clone. Use repos.files.get for one file. The sandbox needs no local Git index and no git push.

TypeScript

const archive = await pierre.repos.archive.get({
  repo_name: memoryRepo,
  ref: pinnedRevision,
  include_globs: ['notes/**'],
});

// Send archive.body to the sandbox and extract the compressed response.

The path above is only an example. Your product chooses the paths and file format.

Use subpaths within one memory repository when every group shares the same access rules, storage lifetime, and delete boundary. For example, a product can use one subpath for each project. A ref policy limits Git branches and tags, not file paths, so enforce subpath access in your product.

If the product needs ordinary Git tools, it can create temporary Git URLs instead. See External Sandbox Integration and Ref Policies.

​

Save the agent’s changes

Set expected_target_sha to the commit SHA that was current before the agent made its change. Code Storage accepts the save only if the target branch still points to that commit.

TypeScript

import { RefGuardError, RefUpdateError } from '@pierre/sdk';

// Your product's record of the current commit of each memory repository.
const memoryHeads = new Map<string, string>();

async function saveMemory(updatedRecord: string) {
  try {
    const written = await pierre.repos.commits.create({
      repo_name: memoryRepo,
      author: { email: '[e-mail]', name: 'Agent' },
      commit_message: 'Update API conventions',
      expected_target_sha: pinnedRevision,
      target_branch: 'main',
      files: [{ path: 'notes/api-conventions.md', content: updatedRecord }],
    });

    memoryHeads.set(memoryRepo, written.commit.commit_sha);
    return { status: 'saved', commitSha: written.commit.commit_sha };
  } catch (error) {
    if (error instanceof RefGuardError) {
      return { status: 'conflict' };
    }
    if (error instanceof RefUpdateError && error.result.status === 'precondition_failed') {
      return { status: 'no_changes', commitSha: pinnedRevision };
    }

    throw error;
  }
}

A conflict means that another agent saved first. Do not send the old file content again. Load the current files, apply the intended change to them, and save again with the new commit SHA.

An identical file set returns precondition_failed; the branch still points at the pinned revision. Treat it as success with no new commit.

After a timeout, the save can still have succeeded. Do not resend the same request. Read the current head again, apply the intended change to the current files, and save with the new head as expected_target_sha.

​

Combine changes from separate branches

A product can give each agent session its own branch. Check the merge first, then require main to remain at the commit that you checked.

TypeScript

const sessionId = '7d1e4b';
const sourceBranch = `sessions/${sessionId}`;
const preview = await pierre.repos.previewMerge({
  repo_name: memoryRepo,
  source_branch: sourceBranch,
  target_branch: 'main',
});

if (preview.status === 'clean') {
  await pierre.repos.merge({
    repo_name: memoryRepo,
    source_ref: sourceBranch,
    target_branch: 'main',
    expected_target_sha: preview.target_tip_sha,
    strategy: 'merge',
    commit_message: 'Merge session memory',
    author: { email: '[e-mail]', name: 'Agent' },
  });
}

If the check finds a conflict, load the listed files. Decide in code how to combine both changes before you save again. If the merge itself fails because main moved after the check, run the check again on the new head.

​

Inspect and undo a change

Use repos.commits.list to show file history and repos.diff.get to show one change.

TypeScript

const fileHistory = await pierre.repos.commits.list({
  repo_name: memoryRepo,
  ref: 'main',
  path: 'notes/api-conventions.md',
  limit: 1,
});
const selected = fileHistory.data[0];
const diff = await pierre.repos.diff.get({ repo_name: memoryRepo, ref: selected.sha });

Use repos.commits.restore to create a new commit from an earlier version. The new commit keeps the undo action in history.

TypeScript

const branchHistory = await pierre.repos.commits.list({
  repo_name: memoryRepo,
  ref: 'main',
  limit: 2,
});
const currentHeadSha = branchHistory.data[0].sha;

const restored = await pierre.repos.commits.restore({
  repo_name: memoryRepo,
  target_branch: 'main',
  base_ref: branchHistory.data[1].sha,
  expected_target_sha: currentHeadSha,
  commit_message: 'Restore memory files',
  author: { email: '[e-mail]', name: 'Operator' },
});

This example restores every file from the commit before the newest commit. To restore one file, read its earlier content and save it with a normal file commit.

​

Related workflow

Use Manage Product Files when people edit a complete file set through a product interface. That workflow validates and applies each change before it becomes active.