sipeed/picoclaw · error

sessions not initialized

Error message

sessions not initialized

What it means

The legacy (default) context manager's Clear() must find the agent that owns the session key via agentForSession, then reset that agent's Sessions store. This error fires when the lookup returns nil (no registered agent owns that session key) or the owning agent was built with a nil Sessions store. It is a wiring/key-space mismatch, not an I/O failure.

Source

Thrown at pkg/agent/context_legacy.go:70

			)
		}
	case ContextCompressReasonSummarize:
		m.maybeSummarize(req.SessionKey)
	}
	return nil
}

func (m *legacyContextManager) Ingest(_ context.Context, _ *IngestRequest) error {
	// Legacy: no-op. Messages are persisted by Sessions JSONL.
	return nil
}

func (m *legacyContextManager) Clear(_ context.Context, sessionKey string) error {
	// Routed (non-default) agents keep history in their own session store,
	// so resolve the owning agent instead of assuming the default one.
	agent := m.al.agentForSession(sessionKey)
	if agent == nil || agent.Sessions == nil {
		return fmt.Errorf("sessions not initialized")
	}
	agent.Sessions.SetHistory(sessionKey, []providers.Message{})
	agent.Sessions.SetSummary(sessionKey, "")
	return agent.Sessions.Save(sessionKey)
}

// maybeSummarize triggers summarization if the session history exceeds thresholds.
// It runs asynchronously in a goroutine.
func (m *legacyContextManager) maybeSummarize(sessionKey string) {
	agent := m.al.registry.GetDefaultAgent()
	if agent == nil {
		return
	}

	newHistory := agent.Sessions.GetHistory(sessionKey)
	tokenEstimate := m.estimateTokens(newHistory)
	threshold := agent.ContextWindow * agent.SummarizeTokenPercent / 100

View on GitHub (pinned to 49183d7e8d)

Solutions

1. Use session keys the agent subsystem itself produced (session.BuildMainSessionKey(agentID) or allocateRouteSession) instead of hand-built keys
2. If the key is stale because the agent was removed, treat this error as 'nothing to clear' at the call site and ack the user
3. Ensure agents are constructed with sessions enabled so agent.Sessions is non-nil (standard construction path does this)
4. Re-register the missing agent id if those sessions must stay clearable

Example fix

// before — arbitrary hand-built key
if err := ctxMgr.Clear(ctx, "user-42/main"); err != nil {
    return err
}

// after — key from the session subsystem
key := session.BuildMainSessionKey(agent.ID)
if err := ctxMgr.Clear(ctx, key); err != nil {
    return err
}

agent := al.GetRegistry().GetDefaultAgent() // or the agent you dispatched to
if agent == nil || agent.Sessions == nil {
    return fmt.Errorf("cannot clear: agent or session store missing")
}
key := session.BuildMainSessionKey(agent.ID)
if err := ctxMgr.Clear(ctx, key); err != nil {
    return err
}

When it happens

Trigger: Clear(ctx, key) called with a hand-crafted or stale session key that no agent owns (e.g. after the owning agent was removed from config), or against an AgentInstance constructed without session persistence (nil agent.Sessions).

Common situations: A /clear-style command arriving for a session from a removed agent; multi-agent setups where old session keys linger; custom embeddings calling the ContextManager API with arbitrary key strings instead of keys produced by session.AllocateRouteSession/BuildMainSessionKey.

Related errors

• no default agent for heartbeat
• no agent available for route (agent_id=%s)
• no default agent for system message
• seahorse: create engine: %w
• seahorse assemble: %w

AI-assisted analysis of sipeed/picoclaw@49183d7e8d (2026-08-15). Data as JSON: /api/errors/0c4fb856e337a2ab. Report an issue: GitHub.