MemoryCore: Key Capabilities of the TencentDB Agent Memory System

MemoryCore is the central memory and metadata engine of the TencentDB Agent Memory system, providing unified storage, hierarchical memory processing (L0-L3), hybrid retrieval, and multi-tenant HTTP APIs for AI agent applications.

MemoryCore serves as the backbone of the TencentCloud/TencentDB-Agent-Memory repository, offering a self-contained runtime for persisting and recalling conversational context. It implements a four-layer memory hierarchy and exposes rich TypeScript/Python SDKs and HTTP endpoints that enable agents to capture interactions, extract skills, and retrieve relevant context with minimal configuration.

Hierarchical Memory Storage and Processing

MemoryCore implements a sophisticated four-layer memory hierarchy that processes raw conversations into structured, retrievable knowledge. The core abstractions in MemoryCore/src/core/ handle the pipeline that transforms data across these levels:

• L0 (Conversations): Raw dialogue turns captured from agent interactions
• L1 (Atomic Memories): Distilled facts and insights extracted from conversations
• L2 (Scenarios): Contextual situations that group related atomic memories
• L3 (Profiles): Persistent user and agent characteristics aggregated over time

The storage layer persists these entities and manages their lifecycle, including creation, updating, and aggregation operations.

Hybrid Memory Recall

The recall system supports keyword, embedding, and hybrid retrieval strategies to surface relevant context. BM25 text search works out-of-the-box without external dependencies, while vector similarity search can be enabled via any OpenAI-compatible embedding API.

This dual approach allows agents to retrieve exact matches for known entities while also discovering semantically related information through vector search.

Knowledge and Asset Metadata Management

MemoryCore maintains comprehensive registries for operational metadata. The knowledge metadata registry tracks external sources such as Wiki systems and Code Graphs, recording their identifiers, types, status, associations, and service locations.

The asset metadata management system handles organizational structure, including users, teams, agents, tasks, skills, knowledge assets, memberships, ownership rules, and access relationships. This ensures that memory operations respect organizational boundaries and permission models.

Skill Memory Lifecycle

The Skill Memory subsystem provides full lifecycle management for agent capabilities. Located within the core storage layer, it handles:

• Creation and versioning of skill definitions
• Resource handling for skill dependencies
• Search and routing to match requests with appropriate skills
• Conversation-driven extraction to generate new skills from demonstrated interactions

Agents can register capabilities programmatically and retrieve them contextually during task execution.

Unified API Surface and Multi-Tenant Security

MemoryCore exposes a secure, multi-tenant HTTP API (versions v2 and v3) alongside TypeScript and Python SDKs. Every v3 request requires tenant isolation headers to guarantee data separation:

• x-tdai-team-id: Identifies the organizational tenant
• x-tdai-agent-id: Identifies the specific agent instance
• x-tdai-user-id: Identifies the end user

The gateway implementation in MemoryCore/src/gateway/ routes these authenticated requests to the appropriate storage backends while enforcing access controls.

Capturing Conversations

To persist a conversation turn (L0) via the v3 API:

curl -X POST http://127.0.0.1:8420/v3/conversation/capture \
  -H "Authorization: Bearer $TDAI_GATEWAY_API_KEY" \
  -H "x-tdai-service-id: default" \
  -H "x-tdai-team-id: team-123" \
  -H "x-tdai-agent-id: agent-xyz" \
  -H "x-tdai-user-id: user-abc" \
  -H "Content-Type: application/json" \
  -d '{
        "session_id": "sess-001",
        "turn_id": "turn-001",
        "role": "user",
        "content": "How do I reset my password?"
      }'

Retrieving Atomic Memories

To recall relevant atomic memories (L1) using BM25 retrieval:

curl -X GET "http://127.0.0.1:8420/v3/atomic/search?query=reset+password&limit=5" \
  -H "Authorization: Bearer $TDAI_GATEWAY_API_KEY" \
  -H "x-tdai-service-id: default" \
  -H "x-tdai-team-id: team-123" \
  -H "x-tdai-agent-id: agent-xyz" \
  -H "x-tdai-user-id: user-abc"

Registering Knowledge Sources

To register a new Wiki knowledge source via the metadata API:

curl -X POST http://127.0.0.1:8420/v3/knowledge/register \
  -H "Authorization: Bearer $TDAI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "type": "wiki",
        "name": "ProductDocs",
        "status": "ready",
        "service_url": "http://wiki.internal/api",
        "metadata": { "language": "en" }
      }'

Extracting Skills

To extract or utilize skills from conversation context:

curl -X POST http://127.0.0.1:8420/v3/skill/extract \
  -H "Authorization: Bearer $TDAI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "session_id": "sess-001",
        "skill_id": "skill-knowledge-base",
        "input": "Explain the steps for provisioning a new DB instance."
      }'

Standalone Runtime Architecture

MemoryCore runs as a lightweight gateway defaulting to 127.0.0.1:8420, requiring only SQLite and local file storage for operation. The MemoryCore/Dockerfile enables containerized deployment, while MemoryCore/tdai-gateway.standalone.yaml provides the default configuration template.

The system requires only a compatible LLM API endpoint for memory extraction operations, making it suitable for local development, single-node production deployments, or sidecar configurations in larger orchestration systems.

Adapters such as the OpenClaw plugin (MemoryCore/openclaw-plugin/) and Hermes provider (MemoryCore/hermes-plugin/) demonstrate how lightweight clients can integrate with the gateway using minimal boilerplate.

Summary

• MemoryCore provides centralized memory management for AI agents through a four-layer hierarchy (L0-L3) that processes raw conversations into persistent profiles and scenarios.
• Hybrid retrieval combines BM25 keyword search with optional vector similarity for flexible context recall.
• Metadata registries track knowledge sources and organizational assets, enabling complex multi-agent and multi-team workflows.
• Multi-tenant security enforces strict isolation through required headers (team_id, agent_id, user_id) on every API request.
• Standalone deployment requires only SQLite and runs locally or in containers at 127.0.0.1:8420, with adapters available for TypeScript and Python integration.

Frequently Asked Questions

What is the difference between L0 and L1 memory in MemoryCore?

L0 memory represents raw conversation turns captured directly from user-agent interactions, while L1 atomic memories are distilled facts and insights extracted from those conversations through LLM processing. The pipeline in MemoryCore/src/core/ automatically promotes relevant L0 data to L1 based on importance and uniqueness criteria, making L1 optimized for retrieval and reuse.

Does MemoryCore require an external vector database?

No, MemoryCore does not require an external vector database for basic operation. BM25 text retrieval works out-of-the-box using local SQLite storage. However, developers can enable embedding-based semantic search by configuring an OpenAI-compatible API endpoint in the gateway configuration, allowing hybrid retrieval without deploying separate vector infrastructure.

How does MemoryCore ensure data isolation between different teams?

MemoryCore enforces multi-tenancy through required HTTP headers on every v3 API request: x-tdai-team-id, x-tdai-agent-id, and x-tdai-user-id. The gateway implementation in MemoryCore/src/gateway/ uses these identifiers to partition data at the storage layer, ensuring that memory records, knowledge assets, and skill definitions remain isolated between tenants even when sharing the same runtime instance.

Can MemoryCore run entirely offline or in air-gapped environments?

Yes, MemoryCore supports fully offline operation when configured with local LLM endpoints. The standalone runtime uses SQLite and local file storage by default, requiring no external services except for the optional embedding API. Organizations can deploy the containerized gateway using MemoryCore/Dockerfile and configure tdai-gateway.standalone.yaml to point to internal LLM services, enabling complete air-gapped functionality.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}