Agent Storage

Configure provides persistent storage for agents — a virtual filesystem where data survives restarts, context window resets, and session boundaries. Store memories, skills, configuration, and notes that persist indefinitely.

Directory Structure

Every agent starts with this default directory layout:

Path	Purpose
/soul/	Agent identity — personality, purpose, communication style
/memory/	Accumulated knowledge — one file per day (YYYY-MM-DD.md)
/skills/	Learned capabilities and domain knowledge
/notes/	Freeform notes, drafts, and working documents
/permissions	Access control for peer agents

Three Scopes

storage operations are available through three scopes, each with different access levels and authentication requirements.

Self — Agent's Own Storage

client.self operates on the agent's own storage. Requires only the API key (no user token).

const client = new ConfigureClient('sk_your_api_key');

// Read your soul document
const soul = await client.self.read('/soul/soul.md');

// Write a memory
await client.self.write('/memory/2026-03-16.md', 'Learned that user prefers concise responses');

// List your storage root
const listing = await client.self.ls('/');

User Profile — User's Profile Storage

client.profile provides storage access to a user's profile via read(), ls(), write(), search(), and rm() methods. Each takes token and userId as the first two arguments. Agents can read broadly but can only write under /agents/{their_name}/.

// Read the user's identity
const identity = await client.profile.read(token, userId, '/identity.json');

// Read memories this agent stored for this user
const memories = await client.profile.read(token, userId, '/agents/travelbot/memories/');

// Write a memory about the user (scoped to your agent)
await client.profile.write(
  token, userId,
  '/agents/travelbot/memories/2026-03-16.md',
  'User mentioned they are vegetarian',
);

// List the user's tool connections
const tools = await client.profile.ls(token, userId, '/tools/');

// Search across the user's profile
const results = await client.profile.search(token, userId, 'travel preferences');

Peer — Another Agent's Storage

client.peer(name) provides read-only access to another agent's storage. Access is gated by the target agent's /permissions node.

const peer = client.peer('wealthbot');

// Read another agent's soul
const soul = await peer.read('/soul/soul.md');

// List their skills
const skills = await peer.ls('/skills/');

// Search their storage
const results = await peer.search('investment strategy');

High-Level Helpers

The self scope includes high-level methods that compose multiple storage reads into structured responses.

getProfile

Returns an assembled view of the agent's identity, configuration, skills, and memory summary.

const profile = await client.self.getProfile();

console.log(profile.soul);        // Soul document (markdown string)
console.log(profile.config);      // Configuration object
console.log(profile.skills);      // Array of { path, name }
console.log(profile.memoryCount); // Number of memory entries
console.log(profile.notes);       // Array of { path, name }

// Request specific sections only
const partial = await client.self.getProfile({
  sections: ['soul', 'memory'],
});

getMemories

Returns memory entries with optional date filtering. Reads all files under /memory/ and filters by filename date.

// All memories
const { memories } = await client.self.getMemories();

for (const entry of memories) {
  console.log(`[${entry.date}] ${entry.content}`);
}

// Date-filtered
const { memories } = await client.self.getMemories({
  from: '2026-03-01',
  to: '2026-03-15',
});

remember

Saves a fact to the agent's own memory. Appends to today's memory file at /memory/YYYY-MM-DD.md.

await client.self.remember('Discovered that JSON merge mode is useful for config updates');
await client.self.remember('User base prefers shorter responses on mobile');

Low-Level Operations

These operations are shared across all three scopes (self, profile, peer). The peer scope only supports read operations (ls, read, search).

ls — List Directory

// List root directory
const listing = await client.self.ls('/');
console.log(listing.entries); // Array of { path, type, ... }
console.log(listing.count);   // Number of entries

// List with depth limit
const shallow = await client.self.ls('/memory/', { depth: 1 });

// List with entry limit
const limited = await client.self.ls('/memory/', { limit: 10 });

read — Read File

Returns the file content and metadata, or null if not found. For directory paths (ending with /), returns all files combined.

const result = await client.self.read('/soul/soul.md');

if (result) {
  console.log(result.content); // File content (string or parsed JSON)
  console.log(result.type);    // 'markdown' or 'json'
  console.log(result.path);    // Resolved path
}

// Read a directory (returns combined content)
const allMemories = await client.self.read('/memory/');

write — Write File

Write content to a path. Supports three write modes.

Mode	Behavior
overwrite	Replace the entire file (default)
append	Add content to the end of the file
merge	Shallow JSON merge (JSON files only)

// Overwrite (default)
await client.self.write('/soul/soul.md', '# TravelBot\n\nI help users plan trips.');

// Append to today's memory log
await client.self.write('/memory/2026-03-16.md', '\n- Learned a new travel pattern', {
  mode: 'append',
});

// Merge JSON config
await client.self.write('/config', JSON.stringify({ defaultCurrency: 'JPY' }), {
  type: 'json',
  mode: 'merge',
});

search — Full-Text Search

Search storage content by keyword.

const results = await client.self.search('travel preferences');

for (const hit of results.matches) {
  console.log(`${hit.path} (score: ${hit.score})`);
  console.log(`  ${hit.snippet}`);
}

// Limit search scope
const scoped = await client.self.search('budget', { scope: '/memory/' });

// Limit result count
const top5 = await client.self.search('hotel', { limit: 5 });

rm — Delete File

Delete a file or directory. Deleting a directory removes all children.

// Delete a single file
await client.self.rm('/notes/draft.md');

// Delete a directory and all its contents
await client.self.rm('/notes/old/');

Peer Access and Permissions

By default, an agent's storage is not readable by other agents. To grant access, write a permissions document at /permissions.

// Grant read access to specific agents
await client.self.write('/permissions', JSON.stringify({
  read: ['wealthbot', 'focusai'],
  paths: ['/soul/', '/skills/'],
}), { type: 'json' });

The requesting agent uses client.peer(name) to read the permitted paths. Requests to paths outside the permission scope return empty results.