How to Access MemoryKnowledge OpenAPI Documentation: Swagger UI, REST API, and Markdown Reference

You can access the MemoryKnowledge OpenAPI documentation via the interactive Swagger UI at http://localhost:8421/docs, download the machine-readable spec at /openapi.json, or reference the static Markdown guide in MemoryKnowledge/v3-api-memoryknowledge-doc.md within the TencentDB-Agent-Memory repository.

The MemoryKnowledge Service (KS) in the TencentDB-Agent-Memory repository exposes a RESTful HTTP API on port 8421 with all endpoints prefixed by /v3. Understanding how to access the MemoryKnowledge OpenAPI documentation is essential for integrating Wiki and Code-Graph engines into your agent workflows. The service provides multiple discovery mechanisms ranging from interactive Swagger interfaces to version-controlled Markdown references.

Architecture of the MemoryKnowledge API

The MemoryKnowledge Service is a Hono-based TypeScript server defined in MemoryKnowledge/src/server.ts. It dynamically loads routes from src/routes/ and initializes the HTTP listener on the configured PORT (default 8421).

Key architectural components include:

• API Prefix: All endpoints reside under /v3, configurable via the API_PREFIX environment variable in MemoryKnowledge/src/config.ts.
• Swagger UI: Auto-generated documentation interface available at the /docs endpoint.
• OpenAPI Specification: Machine-readable schema served at /openapi.json.
• Static Documentation: Human-readable reference maintained in MemoryKnowledge/v3-api-memoryknowledge-doc.md.

How to Access MemoryKnowledge OpenAPI Documentation

Interactive Swagger UI

Once the service is running, navigate to http://127.0.0.1:8421/docs in your browser. The Swagger UI displays all /v3/* routes with interactive request panels, allowing you to test endpoints directly without writing client code. This interface reads the OpenAPI specification from the /openapi.json endpoint dynamically.

Machine-Readable OpenAPI Specification

For automated client generation and SDK development, fetch the JSON specification directly:

curl -s http://127.0.0.1:8421/openapi.json > memoryknowledge-openapi.json

This specification includes complete request/response schemas, authentication requirements, and available endpoints for the Wiki and Code-Graph engines.

Static Markdown Reference

The repository contains a comprehensive Markdown file at MemoryKnowledge/v3-api-memoryknowledge-doc.md. This document lists every endpoint, request schema, response envelope, error handling logic, and authentication rules in a format suitable for offline reading and version control tracking.

Starting the Service and Verifying Access

To access the documentation endpoints locally, follow these setup steps:

1. Initialize the environment:

cd MemoryKnowledge
cp .env.example .env   # Edit to configure PORT, API_PREFIX, and other variables

pnpm install

2. Start the development server:

pnpm dev  # Runs the TypeScript server on default port 8421

3. Verify service health (endpoint operates outside the /v3 namespace):

curl -s http://127.0.0.1:8421/health

Expected output:

{ "status": "ok", "timestamp": "2026-08-27T00:00:00Z" }

4. Open the documentation at http://127.0.0.1:8421/docs.

Authentication Requirements

All requests to /v3/* endpoints must include the mandatory header x-tdai-service-id containing your tenant or service identifier. The MemoryKnowledge Service relies on internal network trust and does not require additional authentication tokens or API keys. This header is strictly enforced for all Wiki and Code-Graph operations.

Practical API Usage Examples

List Wiki Resources for a Team

curl -X POST http://127.0.0.1:8421/v3/wiki/list \
     -H "Content-Type: application/json" \
     -H "x-tdai-service-id: t_1" \
     -d '{"team_id":"t_1","limit":20,"offset":0}'

Search Wiki Content Using BM25

curl -X POST http://127.0.0.1:8421/v3/wiki/search \
     -H "Content-Type: application/json" \
     -H "x-tdai-service-id: t_1" \
     -d '{"wiki_id":"wiki-a1b2c3d4","query":"release plan","limit":10}'

Create a Code-Graph Resource

curl -X POST http://127.0.0.1:8421/v3/code-graph/create \
     -H "Content-Type: application/json" \
     -H "x-tdai-service-id: t_1" \
     -d '{"team_id":"t_1","repo_url":"https://github.com/example/repo","branch":"main"}'

Invoke a Code-Graph Exploration Tool

curl -X POST http://127.0.0.1:8421/v3/tools/call \
     -H "Content-Type: application/json" \
     -H "x-tdai-service-id: t_1" \
     -d '{
           "knowledge_id":"cg-e5f6g7h8",
           "tool_name":"explore",
           "params":{"query":"user login logic","maxFiles":12}
         }'

Retrieve OpenAPI Spec Programmatically

const fetch = require('node-fetch');

async function getSpec() {
  const res = await fetch('http://127.0.0.1:8421/openapi.json');
  const spec = await res.json();
  console.log(JSON.stringify(spec, null, 2));
}
getSpec();

Key Source Files

Understanding these files helps you navigate and extend the MemoryKnowledge OpenAPI documentation:

• MemoryKnowledge/src/server.ts: Entry point that creates the Hono application, mounts /v3 routes, and registers the Swagger UI middleware at /docs.
• MemoryKnowledge/src/config.ts: Loads environment variables including PORT, API_PREFIX, and KNOWLEDGE_PUBLIC_BASE_URL.
• MemoryKnowledge/v3-api-memoryknowledge-doc.md: Comprehensive human-readable API reference with request/response schemas and authentication rules.
• MemoryKnowledge/src/routes/wiki.ts: Implements Wiki-related endpoints (/wiki/*) documented in the OpenAPI spec.
• MemoryKnowledge/src/routes/code-graph.ts: Implements Code-Graph endpoints (/code-graph/*).
• MemoryKnowledge/src/routes/tools.ts: Handles /tools/list and /tools/call for agent self-discovery.
• MemoryKnowledge/.env.example: Template for required environment variables including service ID configurations.
• MemoryKnowledge/docker-compose.yml: Container deployment configuration exposing port 8421.

Summary

• Access the interactive Swagger UI at http://localhost:8421/docs when the service is running.
• Download the OpenAPI JSON specification from /openapi.json for SDK generation and offline reference.
• Consult the Markdown documentation at MemoryKnowledge/v3-api-memoryknowledge-doc.md for detailed endpoint descriptions.
• The service listens on port 8421 with all API routes prefixed by /v3 (configurable via API_PREFIX).
• Include the x-tdai-service-id header in all API requests for tenant identification.
• Verify service availability using the health check endpoint at /health outside the /v3 namespace.

Frequently Asked Questions

Where is the MemoryKnowledge OpenAPI JSON specification served?

The machine-readable OpenAPI specification is served at the /openapi.json endpoint when the MemoryKnowledge Service is running. According to the MemoryKnowledge/src/server.ts implementation, this JSON is automatically generated from the route definitions and can be accessed via curl or any HTTP client for programmatic consumption and SDK generation.

What authentication header is required for MemoryKnowledge API requests?

All requests must include the x-tdai-service-id header containing a valid tenant or service identifier (for example, t_1). As implemented in the TencentDB-Agent-Memory source code, no additional API keys or bearer tokens are required because the service operates on internal network trust models.

Can I run the MemoryKnowledge service locally to test the API documentation?

Yes. Clone the TencentDB-Agent-Memory repository, navigate to the MemoryKnowledge directory, copy .env.example to .env, install dependencies with pnpm install, and start the server using pnpm dev. The Swagger UI becomes available at http://127.0.0.1:8421/docs and the OpenAPI specification at http://127.0.0.1:8421/openapi.json.

Is the API prefix /v3 configurable?

Yes. While the default prefix is /v3 as defined in MemoryKnowledge/src/config.ts, you can override it by setting the API_PREFIX environment variable in your .env file or container configuration. This flexibility allows you to deploy the MemoryKnowledge Service behind reverse proxies or in multi-tenant environments with custom routing requirements.

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