Technical Reference

This page collects the deeper details that most first-time users can skip.

MCP Tool Catalog

Dense-Mem MCP tool names use underscore_case.

For memory writes, split large scenarios into semantic entries before calling remember, import_memories, or save_memory. Store one decision, fact, correction, preference, project milestone, or other claim-worthy unit per entry. Claims should point to the smallest supporting fragment; use multiple supported_by IDs only when one claim needs evidence from several entries.

Trace And Context Tools

trace_memory is a read-scoped inspection tool for one anchor:

The response contains:

assemble_context is a read-scoped answer-preparation tool:

The response includes context_block, structured items, clarifications, and truncated. Treat context_block as retrieved data. It is not an instruction source, and the host assistant remains responsible for judgment and final answering.

Community And Dreaming Tools

Community tools are profile-scoped:

detect_community accepts optional gamma, tolerance, and max_levels parameters. It uses the AI_COMMUNITY_MAX_NODES cap before projecting the graph into Neo4j GDS.

recall_memory and GET /api/v1/recall accept use_communities=true. Community expansion is off by default and fills unused recall slots with members from matching persisted communities.

Dreaming tools are also profile-scoped:

Dreams are hypotheses. promote_candidate creates source evidence from user feedback and then relies on normal claim, verification, conflict, and promotion gates.

See Community Memory and Dreaming for operator guidance.

MCP Prompt Catalog

Dense-Mem advertises MCP prompt support during initialize when bundled prompts are available.

The first bundled prompt is export_memory_as_agent_skill. It helps an LLM recall Dense-Mem context for a topic and draft a shareable Agent Skill SKILL.md file. It is separate from memory-pack import/export; generated skill files are not automatically imported into memory.

Memory Pack Tools

For workflow guidance, see Memory Packs. This section is the compact tool and artifact reference.

The older *_skill_pack* tool names remain accepted as hidden compatibility aliases, and legacy dense-mem.skill_pack.v1 artifacts are still accepted.

export_memory_pack returns file-ready artifact data:

The artifact includes exported_at so consumers can see when the portable memory bundle was created. Imports do not treat original claim validity windows as part of the exported memory pack.

Memory packs preserve the selected memory triples and, when available, the support graph that explains why those triples worked. This makes imported memory carry the original experience, not only the final fact.

{
  "schema_version": "dense-mem.memory_pack.v1",
  "name": "blog-writing",
  "description": "Reusable blog-writing workflow",
  "exported_at": "2026-06-02T01:30:00Z",
  "items": [
    {
      "subject": "assistant",
      "predicate": "has_skill",
      "object": "write a launch blog from project decisions",
      "source_kind": "source_fact",
      "source_id": "fact_123",
      "support_claim_ids": ["claim_123"],
      "support_fragment_ids": ["fragment_123"]
    }
  ],
  "support": {
    "claims": [
      {
        "claim_id": "claim_123",
        "subject": "assistant",
        "predicate": "has_skill",
        "object": "write a launch blog from project decisions",
        "supported_by": ["fragment_123"]
      }
    ],
    "fragments": [
      {
        "fragment_id": "fragment_123",
        "content": "Use the project decisions as supporting claims before drafting.",
        "source_type": "chat",
        "authority": "user"
      }
    ]
  }
}

Use include_support=false only when the export must omit source evidence. The default supported artifact is better for transferring operational skill because imports can rebuild the supporting fragments and claims.

HTTP API Surface

Legacy aliases under /api/v1/profiles/{profileId} remain registered for older API-key lifecycle clients, but new integrations should use the team routes.

Header-scoped memory routes derive the team and profile from the bearer API key. Do not send X-Team-ID for normal memory routes.

Team metadata updates and team-profile lifecycle routes require a manager key for that team. Knowledge routes still use read/write scopes. A write-scoped member key can write memory but cannot list, create, rename, rotate, or delete other profiles.

Recall Endpoint

GET /api/v1/recall

Common query parameters:

Example:

curl "http://localhost:8080/api/v1/recall?query=preferences" \
  -H "Authorization: Bearer $DENSE_MEM_API_KEY"

Read-Only Keys

Use read-only keys for automation that should search memory but never write it.

Create one through the API:

curl -X POST "http://localhost:8080/api/v1/teams/$TEAM_ID/profiles" \
  -H "Authorization: Bearer $MANAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"automation-readonly","scopes":["read"],"rate_limit":120}'

Read-only keys can call read routes, recall, search, and read-scoped MCP tools. Write routes return insufficient-permission errors.

User Portal And Control Portal

The user portal is served by the main API server:

http://127.0.0.1:8080/ui

Its API routes live under /ui/api. They authenticate with the current Dense-Mem API key and can return the current session, rotate the current key when it has write scope, read self-scoped telemetry when telemetry is enabled, and inspect dreaming status, dream outputs, and recent cycle runs.

When the current key has manager role, the user portal also shows a Team tab. Managers can update team metadata and create, list, rename, rotate, or delete member profiles. Manager role creation and role changes stay in the control portal.

The control portal manages teams, profiles, profile roles, keys, security-ban settings, runtime config, operation logs, and per-team dream inspection.

It does not browse or edit memory content.

Required setting:

CONTROL_PORTAL_TOKEN=choose-a-long-secret

Local URL:

http://127.0.0.1:8090/

Keep it private.

When telemetry is enabled, the control server also exposes token-protected Prometheus metrics at /metrics; the telemetry compose overlay scrapes that endpoint with TELEMETRY_SCRAPE_TOKEN.

Data Egress

Dense-Mem sends memory-related text to configured AI providers:

Use a self-hosted provider if memory text must stay inside your environment.

Redis And Multi-Instance Deployments

Single-node deployments can leave Redis disabled.

Use Redis when you run more than one Dense-Mem server because rate limits and SSE stream concurrency must be shared across instances.

Rollback Notes

Operational Checks

Useful checks:

docker compose ps
docker compose logs -f server
curl http://localhost:8080/health
curl http://localhost:8080/ready

Useful team commands:

docker compose exec server /app/list-teams
docker compose exec server /app/list-team-profiles --team-id "<team-id>"
docker compose exec server /app/rotate-team-profile-key \
  --team-id "<team-id>" \
  --profile-id "<profile-id>"

Troubleshooting