Workspaces & sessions

Workspaces

A workspace is the boundary an agent operates within.

• Physical workspace: a directory you choose on your machine. The agent works with its files directly.
• Virtual workspace: an isolated directory under ~/.prokopai/workspaces/<uuid>/. Use one for experiments that should not touch an existing project.

Create either type from New Workspace in the client. Permissions, capabilities, sessions, and MCP connections are scoped to that workspace.

Instructions

Prokop includes two instruction files whenever it builds model context:

• ~/.prokopai/AGENTS.md applies to every workspace on the machine.
• <workspace>/AGENTS.md adds rules for one project.

# Project rules

- Use TypeScript strict mode
- Run the focused test before editing another package
- Never commit .env files

These are ordinary files. Keep project instructions in version control when the whole team should share them.

Workspace capabilities

Capabilities add tools and context to a workspace. Configure them under Workspace Settings > Capabilities. Ordinary workspaces start with these capabilities off. Newly promoted agent homes start with Memory, skill management, Session Search, and Scheduling enabled, but Learning remains opt-in.

Capability	What it adds
Memory	Durable user preferences and workspace facts
Skills	Permission for the agent to create and manage reusable skill files
Workflow	Parallel task decomposition and synthesis
Session Search	Search and read earlier conversations
Scheduling	Create and manage recurring or one-shot agent jobs
Learning	Automatically review eligible completed turns and update persistent knowledge

Memory, Skills, Session Search, and Scheduling have permission risk settings. Each setting controls when the related tool must ask before an operation.

Memory

Memory is deliberately small and inspectable:

• <workspace>/.prokopai/USER.md stores user preferences, up to 1,500 characters.
• <workspace>/.prokopai/MEMORY.md stores project facts, commands, and non-obvious fixes, up to 2,500 characters.

When Memory is enabled, both files are included in model context on each turn. You can read, edit, version, or delete them yourself.

Skills

Skills are conditional instruction sets stored at:

<workspace>/.agents/skills/<skill-name>/SKILL.md

Each skill has a name, a short trigger description, and a Markdown procedure. Unlike AGENTS.md, the full procedure is not included automatically. The agent sees available skill descriptions and calls the skill tool to load one when it matches the task.

---
name: release-check
description: Load before preparing a release
---

# Release check

1. Read the changelog.
2. Run the package-level checks.
3. Verify the built artifact.

Existing skills can be loaded when they are available to the active preconfig. If skill management is enabled, the agent can also create, patch, update, and remove workspace skill files. You remain in control because the result is still plain Markdown on disk.

Learning

Learning is opt-in automatic knowledge review, not model training. It uses your connected model provider to review eligible completed turns and save useful facts, preferences, or procedures for future sessions. These reviews consume model usage separately from your foreground conversations.

There are two destinations:

Where you enable Learning	What it updates	What it reviews
Project workspace	Shared workspace memory and optionally workspace skills	Eligible turns from that workspace
Agent home	The owning agent’s personal memory and optionally personal skills	Eligible turns attributed to that agent from its configured source workspaces

Workspace learning can have multiple learners, each with its own preconfig, model choice, instructions, and timing. An agent home has one learner tied to its owning agent. You can override the learning model or inherit the learner’s preconfig model.

Dependencies

• Enabling Learning also enables Memory and Session Search in the workspace where you configure it.
• Disabling either dependency disables Learning. Memory and Session Search can still be used without Learning.
• Improve skills allows automatic skill creation and refinement. It also requires skill management; turning it on in the client enables that capability.
• With Improve skills off, learning can update memory without changing skills.

Learning is separate from Scheduling. You do not need to create a scheduled job for it.

Sources and exclusions

In an agent home’s Learning settings, choose All eligible workspaces or Selected workspaces. Personal learning uses turns attributed to that agent, not every conversation in a selected project.

Each ordinary workspace has a Use as personal learning source switch. Turning it off excludes that project’s conversations from automatic personal learning while allowing its own shared workspace learning to remain enabled. This is a learning control, not a general restriction on session-search access.

A session’s menu provides an Exclude/Allow learning toggle. Excluded conversations are not eligible learning sources. Learning-generated sessions are not reused as learning evidence; automated sessions are excluded by default.

Timing

Reviews do not run after every message. Each learner has three timing controls:

• Idle time: how long relevant activity should be quiet before a review.
• Minimum interval: the cooldown between review starts.
• Maximum pending time: how long eligible material can wait before a review becomes due even without an idle period, still subject to the minimum interval.

The defaults are 30 minutes idle and a two-hour minimum interval for workspace learning, or 60 minutes idle and a 24-hour minimum interval for personal learning. Both use a 24-hour maximum pending time. A review still needs eligible material and cannot overlap another active review for that workspace.

Agents and their homes

Promoting a preconfig to an agent gives it a persistent home workspace and personal knowledge that follows it across projects. The home is a workspace with its own sessions, files, and local capabilities. You do not need to move your project into it to use the agent.

Keep these knowledge stores distinct:

• Project knowledge: workspace memory and skills, shared by sessions in that project when the relevant capabilities are available.
• Personal agent knowledge: memory and skills carried by the agent across workspaces.
• Home-local knowledge: the home workspace’s own workspace memory and skills, separate from the agent’s personal knowledge.

The home’s Learning settings configure personal learning for its owning agent. Its Memory and Skills capability switches control the home’s local workspace tools, not a global permission policy for that agent. The separate agent_memory and agent_skill_manage tools are available to persistent agents independently of those home switches.

For setup steps and a video, see Set up an agent and workspace capabilities.

Workflow and subagents

A preconfig can allow a session to delegate focused work to subagents. Each subagent has isolated message history, inherits the workspace, and can be resumed later. Delegation is limited to two levels of depth.

The Workflow capability is for larger parallel work when the active preconfig permits subagents. It decomposes a task, runs independent parts through up to five leaf agents concurrently, then returns a synthesis instead of filling the parent context with every intermediate result.

Sessions

A session is one conversation thread. It has its own message history, model, preconfig, and run state. Prokop can keep unlimited sessions in a workspace, with up to six visible together in board view.

When starting a session, choose a model and optionally a preconfig. A preconfig bundles the system prompt, available tools, default model, skill scope, temperature, and subagent rules. You can switch preconfigs mid-session without discarding the conversation.

Session controls

• Queue: send another message while the agent is working. Messages are delivered in order.
• Interrupt: stop the active generation and its running subagents.
• Fork: branch at any message and continue in a separate session.
• Revert: discard later messages and return to an earlier point.
• Compact: summarize older context when a conversation approaches the model limit.

Goal mode

Goal mode turns one request into a bounded multi-turn loop.

1. Choose Goal instead of Chat.
2. Define a completion condition.
3. Set the maximum number of turns.
4. The agent works, then a separate evaluator checks the available evidence.
5. If the condition is not met, the agent receives another turn.

The evaluator inspects a bounded summary of the recent conversation and tool output rather than trusting a claim that the task is done. A goal ends as met, failed, or cancelled. You can stop it at any time.

MCP connections

Each workspace can connect to local stdio or remote Streamable HTTP/SSE MCP servers. Configuration lives in <workspace>/.prokopai/mcp.json. Remote definitions can include request headers.

Connected MCP tools appear alongside Prokop’s built-in tools. See Configuration for the file format.

Terminal sessions

The client includes persistent PTY terminals with multiple tabs. They belong to the workspace and can continue across chat sessions. Agent terminal output can also appear as a rendered tool result in the conversation.

Data locations

Data	Location
Sessions, messages, permissions	~/.prokopai/data/agent.db
Global instructions	~/.prokopai/AGENTS.md
Workspace instructions	<workspace>/AGENTS.md
Memory	<workspace>/.prokopai/USER.md and MEMORY.md
Skills	<workspace>/.agents/skills/
Agent home workspace	~/.prokopai/agents/<agent-id>/home/
Personal agent memory	~/.prokopai/agents/<agent-id>/USER.md and MEMORY.md
Personal agent skills	~/.prokopai/agents/<agent-id>/skills/
MCP configuration	<workspace>/.prokopai/mcp.json

Next: review the tool catalog or configure models and providers.