1 line
3.2 KiB
Plaintext
1 line
3.2 KiB
Plaintext
Project Sentinel: MCP Checkpointing & State PersistenceVersion: 3.0.0-EnterpriseModule: 15-Workflow-CheckpointMaps to: docs/workflows/MCP_CHECKPOINTING.mdScope: Session persistence, context serialization, and multi-device agent handoff.1. The Persistence ProblemStandard Agent sessions are ephemeral. If the user closes the laptop, the Agent forgets "Thought Process." Sentinel solves this by decoupling State from Session.1.1 The "Save Game" ConceptSentinel treats development like a video game. You can save at any point and resume exactly where you left off, even on a different machine.2. Checkpoint Architecture2.1 What is persisted?A Sentinel Checkpoint (.sentinel/checkpoints/ckpt-[hash].json) contains:DB State: A dump of the active Sprint and Tasks.Git State: The current Branch and Commit Hash.Context Profile: Which docs were mounted? (e.g., profile:backend).Agent Scratchpad: A summary of the Agent's current "Plan" or "Blockers" (extracted via get_agent_summary tool).2.2 Creating a CheckpointTrigger:Manual: Agent calls create_checkpoint("End of Day").Auto: Every 1 hour or upon git commit.Process:Sentinel locks the DB.Serializes the current state tables to JSON.Compresses the JSON.Saves to disk.3. Resuming Sessions (The Handoff)3.1 Local ResumeScenario: User restarts the Sentinel binary.Logic:Sentinel checks .sentinel/state.db.Finds active sprint.Welcome Message: "Welcome back. You were working on Task T-101. Last status: Unit Tests Failing. Resume context?"3.2 Peer-to-Peer HandoffScenario: Dev A hands off a task to Dev B.Mechanism:Dev A: archive_checkpoint_to_git().Sentinel commits the .sentinel/state.db (sanitized) to a hidden branch sentinel/handoff/T-101.Dev B: load_checkpoint_from_git("origin/sentinel/handoff/T-101").Sentinel pulls the DB state.Sentinel checks out the corresponding feature branch.Sentinel loads the Context Profile.Result: Dev B's Agent knows exactly what Dev A's Agent was thinking.4. Context SerializationHow do we persist the "Memory" of the Agent?4.1 The Scratchpad BufferSentinel maintains a special table agent_memory.Usage: The Agent can use the tool remember(key="auth_strategy", value="Using JWT with RS256").Persistence: This data survives restarts.Retrieval: When the Agent boots, Sentinel injects these key/value pairs into the system prompt:RECALLED MEMORY:auth_strategy: Using JWT with RS256api_endpoint: /v1/login4.2 Vector Context (Advanced)If Sentinel is configured with a local Vector Store:Checkpoint: Sentinel flushes the in-memory vector embeddings to disk (vectors.index).Resume: Sentinel mmaps the index file, restoring instant semantic search capabilities without re-indexing the documentation.5. Security of Checkpoints5.1 Secret ScrubbingRule: Checkpoints must never contain .env secrets.Enforcement:Before serializing the "Agent Scratchpad" or "DB State", Sentinel runs the PII Redaction Regex.If a secret is found, it is replaced with [REDACTED] before writing to the JSON checkpoint.5.2 EncryptionConfiguration: sentinel.config.encrypt_checkpoints = true.Implementation: Sentinel encrypts the checkpoint file using AES-256-GCM with a key derived from the User's machine ID or a passphrase. This prevents a stolen checkpoint file from leaking architecture details. |