How purrpod/purrcat works
PurrCat is a local-first personal AI agent framework with desktop, web, and terminal interaction surfaces. A user enters chat or a task; the agent manages a session, executes model- and tool-backed work, and can retain or retrieve memories. The product also supports editable DAG workflows, proactive sensors, MCP and skill extensions, and agent evolution. The README documents these capabilities; sampled source confirms session management, model retry and key allocation, storage engines, sensor subprocesses, and desktop hosting. Some API-to-runtime wiring is not sampled, so uncertain links are omitted.
Main entry points: agent.py Agent loop · api API routes · manager.py Session manager · worker_agent.py Memory digestion
Components 25
User interaction
- Desktop shell
electron/main.js - Web UI
ui/src/App.tsx - API routes
src/server/api
Agent runtime
- Python entry
main.py - Session manager
src/agent/manager.py - Agent loop
src/agent/agent.py - Session history
src/agent/session_store.py - Model facade
src/model/facade/model.py - Key scheduling
src/model/manager/key_manager.py - LLM client
src/model/core/llm_client.py
Agent capabilities
- Workflow engine
src/harness/process.py - Workflow nodes
src/harness/node - Agent tools
src/tool
Memory system
- PurrMemo client
src/memory/purrmemo/client.py - Memory digestion
src/memory/purrmemo/core/memory_worker/worker_agent.py - Episodic store
src/memory/purrmemo/core/storage/event_engine.py - Vector store
src/memory/purrmemo/core/storage/vector_engine.py - Knowledge graph
src/memory/purrmemo/core/storage/graph_engine.py
Extensions and perception
- Sensor manager
src/sensor/manager.py - MCP sessions
src/tool/callmcp/session_manager.py - Agent evolution
src/evolve - Execution paradigms
src/utils/paradigm_api.py
Other components
- User
- Model provider
- Sensor subprocesses
Connections 26
- User → Desktop shell: uses
- User → Web UI: uses
- User → API routes: requests
- Desktop shell → API routes: hosts backend
- Web UI → API routes: calls
- API routes → Python entry: serves
- Python entry → Session manager: starts
- Session manager → Agent loop: creates
- Session manager → Session history: loads and saves
- Agent loop → Model facade: requests completion
- Agent loop → Agent tools: dispatches tools
- Agent loop → Workflow engine: runs workflows
- Workflow engine → Workflow nodes: executes
- Model facade → Key scheduling: allocates keys
- Model facade → LLM client: calls
- LLM client → Model provider: sends requests
- Agent loop → PurrMemo client: uses memory
- PurrMemo client → Memory digestion: digests memories
- Memory digestion → Episodic store: records events
- Memory digestion → Vector store: stores embeddings
- Memory digestion → Knowledge graph: updates relations
- Sensor manager → Sensor subprocesses: launches and monitors
- Sensor subprocesses → Sensor manager: sends JSON-RPC
- Agent tools → MCP sessions: calls MCP tools
- API routes → Agent evolution: exposes evolution
- Session manager → Execution paradigms: resolves paradigm