Load Agent Memory

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.

const history = await memoryRepo.listCommits({ branch: 'main', limit: 1 });
const pinnedRevision = history.commits[0].sha;

history = await memory_repo.list_commits(branch="main", limit=1)
pinned_revision = history["commits"][0]["sha"]

history, err := memoryRepo.ListCommits(ctx, storage.ListCommitsOptions{
	Branch: "main",
	Limit:  1,
})
if err != nil {
	return err
}
pinnedRevision := history.Commits[0].SHA

Use createTag() 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 & Security for token details. Use getArchiveStream with file patterns to fetch a group of memory files without a git clone. Use getFileStream for one file. The sandbox needs no local Git index and no git push.

const archive = await memoryRepo.getArchiveStream({
  ref: pinnedRevision,
  includeGlobs: ['notes/**'],
});

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

archive = await memory_repo.get_archive_stream(
    ref=pinned_revision,
    include_globs=["notes/**"],
)

# Send the response body to the sandbox and extract the compressed response.

archive, err := memoryRepo.ArchiveStream(ctx, storage.ArchiveOptions{
	Ref:          pinnedRevision,
	IncludeGlobs: []string{"notes/**"},
})
if err != nil {
	return err
}
defer archive.Body.Close()

// 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 Connect a Sandbox and Ref Policies.

Save the agent’s changes

Set expectedHeadSha 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.

import { RefUpdateError } from '@pierre/storage';

try {
  const result = await memoryRepo
    .createCommit({
      author: { email: 'agent@example.com', name: 'Agent' },
      commitMessage: 'Update API conventions',
      expectedHeadSha: pinnedRevision,
      targetBranch: 'main',
    })
    .addFileFromString('notes/api-conventions.md', updatedRecord)
    .send();

  await memoryHeads.set(memoryRepo.id, result.commitSha);
  return { status: 'saved', commitSha: result.commitSha };
} catch (error) {
  if (error instanceof RefUpdateError) {
    if (error.reason === 'conflict') {
      return { status: 'conflict' };
    }
    if (error.reason === 'precondition_failed') {
      return { status: 'no_changes', commitSha: pinnedRevision };
    }
  }

  throw error;
}

from pierre_storage import RefUpdateError

try:
    result = await (
        memory_repo.create_commit(
            author={"email": "agent@example.com", "name": "Agent"},
            commit_message="Update API conventions",
            expected_head_sha=pinned_revision,
            target_branch="main",
        )
        .add_file_from_string("notes/api-conventions.md", updated_record)
        .send()
    )

    await memory_heads.set(memory_repo.id, result["commit_sha"])
    return {"status": "saved", "commit_sha": result["commit_sha"]}
except RefUpdateError as error:
    if error.reason == "conflict":
        return {"status": "conflict"}
    if error.reason == "precondition_failed":
        return {"status": "no_changes", "commit_sha": pinned_revision}
    raise

builder, err := memoryRepo.CreateCommit(storage.CommitOptions{
	Author:          storage.CommitSignature{Email: "agent@example.com", Name: "Agent"},
	CommitMessage:   "Update API conventions",
	ExpectedHeadSHA: pinnedRevision,
	TargetBranch:    "main",
})
if err != nil {
	return SaveResult{}, err
}

result, err := builder.
	AddFileFromString("notes/api-conventions.md", updatedRecord, nil).
	Send(ctx)
if err != nil {
	var refErr *storage.RefUpdateError
	if errors.As(err, &refErr) {
		switch refErr.Reason {
		case storage.RefUpdateReasonConflict:
			return SaveResult{Status: "conflict"}, nil
		case storage.RefUpdateReasonPreconditionFailed:
			return SaveResult{Status: "no_changes", CommitSHA: pinnedRevision}, nil
		}
	}
	return SaveResult{}, err
}

if err := memoryHeads.Set(ctx, memoryRepo.ID, result.CommitSHA); err != nil {
	return SaveResult{}, err
}
return SaveResult{Status: "saved", CommitSHA: result.CommitSHA}, nil

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 expectedHeadSha.

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.

const sourceBranch = `sessions/${sessionId}`;
const preview = await memoryRepo.previewMerge({
  sourceBranch,
  targetBranch: 'main',
});

if (preview.status === 'clean') {
  await memoryRepo.merge({
    sourceBranch,
    targetBranch: 'main',
    expectedTargetSha: preview.targetTipSha,
    strategy: 'merge',
  });
}

source_branch = f"sessions/{session_id}"
preview = await memory_repo.preview_merge(
    source_branch=source_branch,
    target_branch="main",
)

if preview["status"] == "clean":
    await memory_repo.merge(
        source_branch=source_branch,
        target_branch="main",
        expected_target_sha=preview["target_tip_sha"],
        strategy="merge",
    )

sourceBranch := fmt.Sprintf("sessions/%s", sessionID)
preview, err := memoryRepo.PreviewMerge(ctx, storage.PreviewMergeOptions{
	SourceBranch: sourceBranch,
	TargetBranch: "main",
})
if err != nil {
	return err
}

if preview.Status == "clean" {
	_, err = memoryRepo.Merge(ctx, storage.MergeOptions{
		SourceBranch:      sourceBranch,
		TargetBranch:      "main",
		ExpectedTargetSHA: preview.TargetTipSHA,
		Strategy:          storage.MergeStrategyMerge,
	})
}

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 listCommits to show file history and getCommitDiff to show one change.

const history = await memoryRepo.listCommits({
  branch: 'main',
  path: 'notes/api-conventions.md',
  limit: 1,
});
const selected = history.commits[0];
const diff = await memoryRepo.getCommitDiff({ sha: selected.sha });

history = await memory_repo.list_commits(
    branch="main",
    path="notes/api-conventions.md",
    limit=1,
)
selected = history["commits"][0]
diff = await memory_repo.get_commit_diff(sha=selected["sha"])

history, err := memoryRepo.ListCommits(ctx, storage.ListCommitsOptions{
	Branch: "main",
	Path:   "notes/api-conventions.md",
	Limit:  1,
})
if err != nil {
	return err
}
selected := history.Commits[0]
diff, err := memoryRepo.GetCommitDiff(ctx, storage.GetCommitDiffOptions{SHA: selected.SHA})

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

const branchHistory = await memoryRepo.listCommits({ branch: 'main', limit: 2 });
const currentHeadSha = branchHistory.commits[0].sha;

const restored = await memoryRepo.restoreCommit({
  targetBranch: 'main',
  targetCommitSha: branchHistory.commits[1].sha,
  expectedHeadSha: currentHeadSha,
  commitMessage: 'Restore memory files',
  author: { email: 'operator@example.com', name: 'Operator' },
});

branch_history = await memory_repo.list_commits(branch="main", limit=2)
current_head_sha = branch_history["commits"][0]["sha"]

restored = await memory_repo.restore_commit(
    target_branch="main",
    target_commit_sha=branch_history["commits"][1]["sha"],
    expected_head_sha=current_head_sha,
    commit_message="Restore memory files",
    author={"email": "operator@example.com", "name": "Operator"},
)

branchHistory, err := memoryRepo.ListCommits(ctx, storage.ListCommitsOptions{
	Branch: "main",
	Limit:  2,
})
if err != nil {
	return err
}
currentHeadSHA := branchHistory.Commits[0].SHA

restored, err := memoryRepo.RestoreCommit(ctx, storage.RestoreCommitOptions{
	TargetBranch:    "main",
	TargetCommitSHA: branchHistory.Commits[1].SHA,
	ExpectedHeadSHA: currentHeadSHA,
	CommitMessage:   "Restore memory files",
	Author:          storage.CommitSignature{Email: "operator@example.com", 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. 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.

Getting Started

Features

Workflows

Reference

Choose the repository and exact version

Load only the required files

Save the agent’s changes

Combine changes from separate branches

Inspect and undo a change

​Choose the repository and exact version

​Load only the required files

​Save the agent’s changes

​Combine changes from separate branches

​Inspect and undo a change

​Related workflow

Choose the repository and exact version

Load only the required files

Save the agent’s changes

Combine changes from separate branches

Inspect and undo a change

Related workflow