Projects And Sessions

ProtoAgent separates the active workspace, UI session summaries, and model-facing conversation memory. This distinction matters for debugging.

Active Project

The active project is the root of the workspace boundary. It controls:

1. Which files @ can tag.
2. Which files Context Loom indexes.
3. Which paths Explorer and Coder tools may read or write.
4. Which project session id is used for durable Architect memory.

Commands:

proto-cli project
proto-cli project set ~/projects/my-app
proto-cli project clear

TUI:

/project
/project ~/projects/my-app
/project clear

The project config is stored at:

~/.protoagent/project.json

The config contains:

Key	Meaning
active_project	Current project path.
recent_projects	Up to 12 recently opened project paths.
context_memory_enabled	Optional boolean controlling persistent ProtoLink session use. Defaults to on.

Path Resolution

Relative project paths are resolved from the launch workspace. If the CLI is started from cli/, default_launch_workspace() recognizes the repo root when whitepaper.md is present.

The core tools use safe_path() to reject access outside the selected workspace.

File Tags

Tagged context lets the user explicitly include a file or directory in a task:

explain @src/auth.rs
summarize @"docs/space path.md"

The Python core loads at most six tags, with a total tagged-context budget. File tags are highest-priority context and are passed before the automatically chosen Context Loom evidence.

Session Ids

The Rust CLI derives a stable project session id from the workspace path:

protoagent-project-<hash>

When persistent memory is on, that id is passed to ProtoLink. When memory is off, the core uses task-local state and does not persist project conversation continuity.

Commands:

/context on
/context off
/context memory

Rust UI Session Ledger

The Rust UI stores a product-facing session ledger at:

~/.protoagent/sessions.json

This is not the model's authoritative conversation memory. It is a UI/history ledger used for:

1. Recent project session display.
2. Last prompts and answer previews.
3. Provider/model metadata.
4. Event counts and timeline summaries.
5. Reopening a workspace from a saved session.

Commands:

/sessions
/sessions choose
/session rename NAME
/last

Shell:

proto-cli sessions

Model-Facing Memory

Model-facing conversation state lives in ProtoLink storage:

~/.protoagent/conversations.sqlite

The Python core controls this state through ProtoLink APIs:

Command	Core function
/context history	describe_saved_histories()
/context compact	compact_saved_histories()
/context reset	reset_saved_histories()
automatic run compaction	compact_agent_histories_for_run()

/context reset clears ProtoLink conversation histories and trims the Rust UI session history for the active session to zero stored turns.

What To Update

If project selection changes, update:

1. cli/src/main.rs
2. cli/src/terminal_ui/project.rs
3. this page

If session persistence changes, update:

1. cli/src/sessions.rs
2. core/protoagent_core/history.py
3. this page
4. Core / State And Memory