Memory
## Pipali Analysis — ATIF Conversation Memory & Agent Loop (July 2026) ### What Pipali Is Desktop AI coding assistant (Tauri + Bun). Similar to Cursor/Claude Code but with a transparent, trajectory-based conversation memory system called ATIF. ### ATIF (Agent Trajectory Interchange Format) A structured format for conversation history. Every conversation is a trajectory of steps: ``` ATIFTrajectory { schema_version: "ATIF-v1.4" session_id: uuid agent: { name, version, model_name } steps: ATIFStep[] ← the conversation final_metrics: { total_prompt_tokens, total_completion_tokens, total_cost_usd } } ``` Each ATIFStep: ``` ATIFStep { step_id: number ← sequential (1-based) timestamp: string ← ISO 8601 source: "user" | "agent" | "system" message?: string ← text content reasoning_content?: string ← chain-of-thought tool_calls?: ATIFToolCall[] ← function invocations observation?: ATIFObservation ← tool results metrics?: ATIFMetrics ← per-step token/cost tracking extra?: Record<string, any> } ``` ### Agent Loop (Director) The `research()` function is an async generator that yields iterations: 1. `pickNextTool()` — calls LLM with context, gets back tool calls or message 2. If tool calls → `executeToolsInParallel()` → yield results → loop 3. If no tool calls → yield final message → break 4. Handles warnings, retries, soft interrupts, abort signals 5. Max iterations with threshold-based early stopping ### Context Assembly (Key Pattern) `generateChatmlMessagesWithContext()` builds the LLM input: 1. System message first 2. Find most recent compaction step — only process steps FROM that point 3. For each step: - User messages → `role: "user"` - Agent messages → raw output items (reasoning, messages, tool calls) OR fallback construction - Tool results → `function_call_output` items 4. Current query appended at end ### Compaction When context gets too long, a compaction step summarizes earlier history. Future context assembly starts from the compaction point, not the beginning. ### User Context Loaded from a markdown file with frontmatter (name, location, language) and instructions. Injected into system prompt. ### What Makes Pipali Great 1. **Transparent trajectory** — every step is recorded with metrics 2. **Tool execution pipeline** — built-in tools (file ops, shell, web) + MCP tools 3. **Compaction** — context window management via summarization 4. **Soft interrupts** — user can send new message while agent is running 5. **Fork conversations** — branch from any point 6. **Confirmation system** — tool approval before execution ### What We Can Improve (SurrealDB-based) 1. **No load/summarize** — use SurrealQL queries to assemble context on-demand 2. **Omit old tool outputs** — query excludes old tool_call_output, keeps only recent + summaries 3. **Graph-based memory** — entities/relations from conversations stored as graph nodes 4. **Hybrid search** — find relevant past conversations by vector + BM25 5. **Supersession** — facts from conversations can supersede each other 6. **Traces** — every retrieval decision is auditable 7. **DEFINE API** — iPhone shortcuts can query conversation history directly ### Architecture Mapping | Pipali Concept | DocuClear Equivalent | |----------------|---------------------| | ATIFTrajectory | Thread (in SurrealDB) | | ATIFStep | Message (in SurrealDB) | | Director (research loop) | Agent loop (in Worker) | | generateChatmlMessagesWithContext | SurrealQL context assembly | | Compaction | Context window management via queries | | User Context | Workspace soul/persona | | MCP tools | SurrealDB tools + external tools | | Confirmation system | Tool approval cards | | Fork conversation | Branch from any point |
Tags: research, pipali, atif, agent-loop, context-assembly, project:docuclear_clearspace, kind:semantic — Source: claude — 2026-07-18 21:39:41 UTC