[Proposal] OpenViking long-term memory middleware for AgentScope

[Mchenr]

Summary

I would like to explore an AgentScope-native integration with OpenViking, implemented as an optional long-term-memory middleware.

The goal is to let an AgentScope agent automatically:

1. retrieve relevant OpenViking memories before reasoning;
2. inject a bounded memory hint into the current turn;
3. append the completed exchange to a stable OpenViking Session;
4. commit the Session for asynchronous memory extraction.

Before starting implementation, I would like to confirm whether this integration is welcome in AgentScope core and align on the appropriate first-PR scope.

Motivation

AgentScope already provides several long-term-memory integrations, including AgenticMemoryMiddleware, Mem0Middleware, and ReMeMiddleware.

OpenViking provides a complementary model centered on a context filesystem, Sessions, memory extraction, semantic retrieval, resources, skills, and actor-peer scopes. It currently has integrations with several agent and coding systems, but I could not find an existing AgentScope integration.

Users can call OpenViking manually or expose it through MCP, but that does not provide a standard AgentScope lifecycle for automatic recall and post-turn capture.

AgentScope's middleware hooks appear to provide a natural integration point:

on_reply
  -> retrieve memories using the new user query
  -> wait until AgentScope has ingested the input
  -> inject a bounded memory message
  -> run the normal reasoning/acting loop
  -> record the completed turn into OpenViking

This would follow the existing Mem0/ReMe middleware pattern without introducing a new Agent class or changing the common middleware API.

Identity and isolation

The proposed mapping is:

AgentScope	OpenViking
authenticated user_id	credential-bound OpenViking user
agent_id	actor_peer_id
session_id	stable OpenViking Session

The user identity, API key, and actor peer must come from trusted host application state, never from model-generated tool arguments.

For AgentScope Agent Service, the existing extra_agent_middlewares factory already receives user_id, agent_id, session_id, and workspace. This should allow the application to construct a user-bound middleware without adding user identity to AgentState.

An actor peer is only an agent-level view within one OpenViking user; it must not be treated as a tenant boundary.

Proposed defaults and points requiring maintainer alignment

To make the proposal concrete, the following are the defaults I intend to use for the first implementation. I am raising these points before writing code because they affect repository ownership, dependencies, and public behavior. Unless maintainers prefer a different direction, I will proceed with these defaults.

1. Integration location: AgentScope core first

Proposed default: Add OpenVikingMiddleware to AgentScope's existing long-term-memory middleware package.

This follows the Mem0 and ReMe precedent and gives users a consistent import:

from agentscope.middleware import OpenVikingMiddleware

Accepting it into core also means accepting some long-term responsibility for its API, tests, documentation, and dependency compatibility. If maintainers prefer not to add another provider-specific middleware, I can instead maintain a standalone agentscope-openviking package and contribute an example or documentation link upstream.

Maintainer guidance requested: Is AgentScope core the appropriate home for this integration?

2. First-PR scope: automatic memory only

Proposed default: Support static_control only in the first PR.

receive a user query
  -> retrieve relevant OpenViking memories
  -> inject a bounded memory hint
  -> run the normal AgentScope reply
  -> record and commit the completed exchange

The first PR would not add model-controlled search_memory or remember tools. Those require additional decisions about schemas, permissions, duplicate writes, and overlap with OpenViking MCP. They can be discussed as follow-up work.

Maintainer guidance requested: Is a static_control-only first version sufficiently useful, or is control-mode parity with Mem0 required for acceptance?

3. Client layer: use the lightweight OpenViking SDK directly

Proposed default: Depend directly on openviking-sdk as an optional, lazily imported dependency.

AgentScope
  -> openviking-sdk
  -> remote OpenViking server

This avoids introducing LangChain as an integration dependency. The trade-off is that the middleware must own Session creation, message conversion, commit behavior, duplicate-write protection, and failure handling. The higher-level langchain-openviking package implements some recording semantics, but adds another framework dependency.

I intend to keep the first version small and provide only delivery guarantees that can be tested reliably, rather than claiming durable or exactly-once writes.

Maintainer guidance requested: Is a direct optional dependency on openviking-sdk consistent with AgentScope's dependency policy?

4. Memory injection: follow existing middleware conventions

Proposed default: Follow the existing Mem0/ReMe approach and inject retrieved memory as a framework-owned Msg with a reserved name.

The message will be bounded, distinguishable from user/assistant messages, excluded from write-back, and treated as contextual data rather than trusted instructions.

This matters because injected messages become part of agent.state.context and interact with serialization, compression, retries, and later turns. The first PR will not introduce a new shared memory-message abstraction.

Maintainer guidance requested: Is the current Mem0/ReMe injection pattern acceptable, or is there an upcoming shared convention this integration should follow?

5. Client lifecycle: follow ReMe's explicit cleanup model

Proposed default: Follow the existing ReMe precedent and expose an explicit asynchronous close() method.

memory = OpenVikingMiddleware(...)

try:
    agent = Agent(..., middlewares=[memory])
    await agent(...)
finally:
    await memory.close()

The first PR will not redesign MiddlewareBase lifecycle management or introduce a multi-user client registry. Application-level pooling, idle eviction, and automatic middleware shutdown can be considered separately.

Maintainer guidance requested: Is following ReMe's explicit close() convention acceptable for the first version?

Intended first-PR boundary

Unless maintainers request changes, the first PR will be limited to:

• one optional OpenVikingMiddleware;
• static_control only;
• direct, lazy use of openviking-sdk;
• bounded recall and framework-owned memory injection;
• current-turn write-back to a stable OpenViking Session;
• explicit close(), following ReMe;
• mocked unit tests with no live network dependency;
• one focused standalone example.

It will not include Agent-controlled memory tools, resource/skill ingestion, credential provisioning, client registries, or changes to the common middleware lifecycle.

Out of scope

• replacing AgentScope state or workspace persistence;
• OpenViking server lifecycle management;
• tenant provisioning or credential storage inside AgentScope;
• arbitrary viking:// filesystem operations;
• quality or latency claims without comparative evaluation.

If the direction is accepted, I am willing to implement the smallest agreed vertical slice, including tests and examples, and maintain the integration through review iterations.