Total Agent Memory

https://totalmemory.dev/docs
Admin
Total Agent Memory (TAM) is a local-first MCP server that provides persistent memory across...
Tokens:177,728
Snippets:1,422
Trust Score:5.1
Update:4 days ago
Show doc for...
Tokens:
Raw
### Install and start the server with Docker Compose

Source: https://totalmemory.dev/docs/teams/install

Clone the repository and start the team server using the provided Docker Compose configuration.

```bash
git clone https://github.com/vbcherepanov/total-agent-memory.git
cd total-agent-memory
docker compose -f docker-compose.team.yml build
docker compose -f docker-compose.team.yml up -d
```

--------------------------------

### Install and Configure Hermes Plugin

Source: https://totalmemory.dev/docs/integrations/hermes

Install the memory plugin and initiate the setup process for Hermes Agent.

```bash
hermes plugins install vbcherepanov/hermes-tam-memory#hermes_tam_memory
hermes memory setup tam
```

--------------------------------

### Initialize Team Server and Manage Users

Source: https://totalmemory.dev/docs

Commands to set up a virtual environment, install the package, add users and teams, assign roles, and start the server.

```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install total-agent-memory==14.9.0

tam-team --root ./team-data user-add alice 'Alice'
tam-team --root ./team-data user-add bob 'Bob'
tam-team --root ./team-data team-add engineering 'Engineering'
tam-team --root ./team-data member alice engineering editor
tam-team --root ./team-data member bob engineering editor
tam-team --root ./team-data token-create alice --client codex --out ./alice.token
tam-team --root ./team-data token-create bob --client cursor --out ./bob.token
tam-team --root ./team-data serve --host 127.0.0.1 --port 3738
```

--------------------------------

### Run the setup wizard

Source: https://totalmemory.dev/docs/setup-wizard

Commands to initiate the setup wizard or reconfigure existing settings.

```bash
tam setup                # first setup
tam setup --reconfigure  # change it later; the current values are the defaults
```

--------------------------------

### Configure dashboard port

Source: https://totalmemory.dev/docs/troubleshooting

Example of setting the dashboard port during installation.

```bash
DASHBOARD_PORT=37800 ./install.sh --ide claude-code
```

--------------------------------

### task_create arguments example

Source: https://totalmemory.dev/docs/tools/task_create

Example of the JSON arguments required to initialize a new task.

```json
{
  "task_id": "BILL-142",
  "description": "Add rate limiting to the public REST API",
  "level": 2
}
```

--------------------------------

### onboarding_submit Arguments Example

Source: https://totalmemory.dev/docs/tools/team/onboarding_submit

Example JSON payload for submitting quiz answers, including both choice-based and text-based responses.

```json
{
  "module_id": "mod_deploy",
  "answers": [
    {
      "question_id": "q_deploy_days",
      "choices": [
        1
      ]
    },
    {
      "question_id": "q_billing",
      "text": "Billing is high-risk, so a second reviewer catches mistakes."
    }
  ]
}
```

--------------------------------

### Install via Homebrew

Source: https://totalmemory.dev/docs/install

Installs the Total Memory command-line tools into the Homebrew prefix.

```bash
brew install vbcherepanov/tap/total-memory
```

--------------------------------

### Install via pipx, pip, or uv

Source: https://totalmemory.dev/docs/install

Standard Python installation methods for the total-agent-memory package.

```bash
pipx install total-agent-memory     # isolated, puts the commands on PATH
uvx total-agent-memory              # one-off run without installing
pip install total-agent-memory      # into the current virtual environment
```

--------------------------------

### Install via Script on Linux/macOS

Source: https://totalmemory.dev/docs/install

Clones the repository and runs the install script for a specific IDE integration.

```bash
git clone https://github.com/vbcherepanov/total-agent-memory.git ~/total-agent-memory
cd ~/total-agent-memory
bash install.sh --ide claude-code
```

--------------------------------

### onboarding_grade Arguments Example

Source: https://totalmemory.dev/docs/tools/team/onboarding_grade

Example JSON arguments for the onboarding_grade tool, including the required attempt_id, question_id, and score.

```json
{
  "attempt_id": 17,
  "question_id": "q_billing",
  "score": 2,
  "comment": "Right: the second reviewer is the point."
}
```

--------------------------------

### Choose setup mode

Source: https://totalmemory.dev/docs/setup-wizard

The initial prompt for selecting between personal memory or a company server.

```text
Step 1  Choose how you use it
  How will you use total-agent-memory?
    1) Just me         personal memory on this machine, for your own AI clients
    2) Company server  one shared memory server that your teams connect to
  Choose [1]:
```

--------------------------------

### duration_between example arguments

Source: https://totalmemory.dev/docs/tools/memory_temporal_query

Example arguments for the duration_between operation, specifying ISO start and end datetimes.

```json
{
  "op": "duration_between",
  "a": "2026-06-10T00:00:00",
  "b": "2026-09-25T00:00:00"
}
```

--------------------------------

### Build and preview the documentation site locally

Source: https://totalmemory.dev/docs/quick-start

Use these commands to build and preview the production site locally for development or testing purposes.

```bash
npm run build
```

```bash
npm run preview
```

--------------------------------

### memory_export Arguments

Source: https://totalmemory.dev/docs/tools/team/memory_export

Example arguments for the memory_export tool, specifying the scope, starting ID, and limit.

```json
{
  "scope": {
    "kind": "shared"
  },
  "after": 0,
  "limit": 2
}
```

--------------------------------

### Install and run team server on Windows PowerShell

Source: https://totalmemory.dev/docs/teams/install

Commands for setting up a virtual environment, installing total-agent-memory, adding the venv Scripts directory to PATH, and starting the server on 127.0.0.1:3738. The --root flag specifies the data directory; without it, tam-team uses $TAM_TEAM_DIR or ~/.tam-server.

```powershell
py -3 -m venv .venv
.\ .venv\Scripts\python.exe -m pip install total-agent-memory
$env:PATH = "$PWD\.venv\Scripts;$env:PATH"
tam-team --root .\team-data serve --host 127.0.0.1 --port 3738
```

--------------------------------

### Bootstrap and start the team server

Source: https://totalmemory.dev/docs/teams/dashboard

Use the bootstrap-admin command to create the initial superadmin and generate an invite code, then start the server.

```bash
tam-team --root /srv/tam-team bootstrap-admin alice 'Alice Admin'
# Invite code for alice: 7KQ2-M9XD-...   Valid until ...; single use.
tam-team --root /srv/tam-team serve --host 127.0.0.1 --port 3738
```

--------------------------------

### onboarding_start

Source: https://totalmemory.dev/docs/tools/team/onboarding_start

Enrolls you in a department's onboarding (or resumes it) and returns the plan with your progress and the next step. Requires membership in the department; enrollment is logged in the department's learning log.

```APIDOC
## onboarding_start

### Description
Enrols you in a department's onboarding (or resumes it) and returns the plan with your progress and the next step.

### Method
MCP tool call

### Endpoint
onboarding_start

### Parameters
#### Path Parameters
- **team_id** (string) - Required - Department identifier (pattern ^[a-zA-Z0-9_-]{1,64}$)

### Request Example
{
  "team_id": "eng"
}

### Response
#### Success Response
- **team_id** (string) - Department identifier
- **title** (string) - Onboarding plan title
- **enrolled_at** (string) - Enrollment timestamp
- **newly_enrolled** (boolean) - Whether the enrollment is new
- **plan** (array) - List of modules with lessons and quiz
- **summary** (object) - Progress summary
- **next** (object) - Next step information

#### Response Example
{
  "team_id": "eng",
  "title": "Engineering onboarding",
  "enrolled_at": "2026-09-25T09:12:04.118Z",
  "newly_enrolled": true,
  "plan": [
    {
      "module_id": "mod_deploy",
      "title": "Deploy",
      "status": "in_progress",
      "lessons_completed": 0,
      "lessons_total": 2,
      "lessons": [
        {
          "lesson_id": "les_pipeline",
          "title": "Pipeline",
          "status": "not_started"
        }
      ],
      "quiz": {
        "questions": 4,
        "pass_threshold": 0.8,
        "attempts_left": 3
      }
    }
  ],
  "summary": {
    "lessons_completed": 2,
    "lessons_total": 4,
    "modules_finished": 1,
    "modules_total": 2,
    "percent": 50,
    "updated_lessons": 0
  },
  "next": {
    "action": "lesson",
    "module_id": "mod_deploy",
    "lesson_id": "les_pipeline",
    "title": "Pipeline",
    "hint": "Call onboarding_next to open it."
  }
}
```

--------------------------------

### Run setup in non-interactive company mode

Source: https://totalmemory.dev/docs/setup-wizard

Executes the setup wizard for a company deployment, specifying data directory, host, port, and administrative details.

```bash
tam setup --non-interactive --json --mode company --data-dir /srv/tam --host 0.0.0.0 --port 3737 \
  --public-url https://memory.example.com --deploy manual --company-name "Acme" \
  --admin-id alice --admin-name "Alice Admin" --department eng=Engineering --department ops=Operations \
  --llm ollama --ollama-url http://ollama:11434 --embed-provider fastembed
```

--------------------------------

### Install and run team server on Linux/macOS

Source: https://totalmemory.dev/docs/teams/install

Commands for setting up a dedicated virtual environment, installing total-agent-memory, adding a user, and starting the server on 127.0.0.1:3738. The --root flag specifies the data directory; without it, tam-team uses $TAM_TEAM_DIR or ~/.tam-server. The serve command defaults to 127.0.0.1:3737 unless overridden.

```bash
python3 -m venv /opt/tam-team/.venv
/opt/tam-team/.venv/bin/python -m pip install total-agent-memory
/opt/tam-team/.venv/bin/tam-team --root /srv/tam-team user-add alice 'Alice Moreau'
/opt/tam-team/.venv/bin/tam-team --root /srv/tam-team serve --host 127.0.0.1 --port 3738
```

--------------------------------

### session_init

Source: https://totalmemory.dev/docs/tools/session_init

Loads the most recent unread end-of-session summary for a project. Use at the start of a session to get the next steps and pitfalls from the previous session. By default, the summary is marked as consumed so it is not returned twice.

```APIDOC
## session_init

### Description
Loads the most recent unread end-of-session summary for a project so a new session can pick up where the last one stopped.

### Parameters
- **project** (string) - Optional - Default: "general" - The project name.
- **mark_consumed** (boolean) - Optional - Default: true - Whether to mark the summary as consumed.

### Example
Arguments:
```
{
  "project": "my-api"
}
```

Result shape:
```
{
  "id": "9f1c2a7e4b0d4c1f8e2a6b3c5d7e9f01",
  "session_id": "sess-2026-09-24-a",
  "project": "my-api",
  "summary": "Moved JWT validation into middleware and fixed refresh-token expiry.",
  "highlights": [
    "Auth middleware merged"
  ],
  "pitfalls": [
    "Refresh tokens are stored in UTC; do not compare with local time"
  ],
  "next_steps": [
    "Add rate limiting to /auth/refresh"
  ],
  "open_questions": [],
  "ended_at": "2026-09-24T18:02:11Z",
  "consumed": 0,
  "markdown_stale": false
}
```

Returns {"message": "no pending summary"} when there is nothing to resume. By default the summary is marked consumed so it is not returned twice.

Values are illustrative; the keys follow the server's handler. MCP clients receive the result as JSON text content.

### Server description
The description the server sends to your agent in `tools/list`, captured from the v14.9.0 source:
> At session start: return the most recent unconsumed end-of-session summary with highlights / pitfalls / next_steps.
```

--------------------------------

### Example arguments for onboarding_curriculum_set

Source: https://totalmemory.dev/docs/tools/team/onboarding_curriculum_set

Shows the JSON arguments for creating or replacing a curriculum. The expected_revision must match the current revision from onboarding_curriculum_get, or the request is rejected with a conflict. Record IDs must exist in team memory.

```json
{
  "team_id": "eng",
  "expected_revision": 3,
  "curriculum": {
    "title": "Engineering onboarding",
    "modules": [
      {
        "id": "mod_deploy",
        "title": "Deploy",
        "pass_threshold": 0.8,
        "max_attempts": 3,
        "lessons": [
          {
            "id": "les_pipeline",
            "title": "Pipeline",
            "body": "How a change reaches production.",
            "record_ids": [
              42
            ]
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Manual Claude Desktop configuration

Source: https://totalmemory.dev/docs/quick-start

Use this JSON snippet to manually add the total-agent-memory MCP server to Claude Desktop, for example with a pipx or Homebrew install. Open Settings → Developer → Edit Config and add the server under mcpServers. Claude Desktop does not expand ~, so write the full path. On Windows the npx install puts the server at %USERPROFILE%\.tam\.venv\Scripts\total-agent-memory.exe.

```json
{
  "mcpServers": {
    "memory": {
      "command": "/Users/you/.tam/.venv/bin/total-agent-memory",
      "args": [],
      "env": { "MEMORY_MODE": "fast" }
    }
  }
}
```

--------------------------------

### Install TAM plugin from Claude Code

Source: https://totalmemory.dev/docs/quick-start

Run these two commands inside a Claude Code session to install the TAM plugin. This installs the MCP server, the memory-protocol skill, and capture hooks in one step. If TAM is already installed, the plugin reuses it.

```claude-code
/plugin marketplace add vbcherepanov/total-agent-memory
/plugin install total-agent-memory@vbcherepanov
```

--------------------------------

### Pin version during installation

Source: https://totalmemory.dev/docs/upgrading

Commands to install a specific version instead of the latest.

```bash
npx -y total-agent-memory install --server-version 14.9.0
pip install total-agent-memory==14.9.0
```

--------------------------------

### Check installation status with npx

Source: https://totalmemory.dev/docs/quick-start

Run this command to verify install paths, database size, background helper status, and dashboard availability.

```bash
npx -y total-agent-memory status
```

--------------------------------

### workflow_learn example arguments

Source: https://totalmemory.dev/docs/tools/workflow_learn

Example arguments for the workflow_learn tool, showing a release workflow for a Python package. The name and steps are required; description, trigger_pattern, and project are optional. The project defaults to "general" if omitted.

```json
{
  "name": "release-python-package",
  "steps": [
    "Run the full test suite",
    "Bump version in pyproject.toml",
    "Build wheel and sdist",
    "Upload to PyPI"
  ],
  "description": "Standard release for the core library",
  "trigger_pattern": "release",
  "project": "my-library"
}
```

--------------------------------

### Example arguments for onboarding_quiz_draft

Source: https://totalmemory.dev/docs/tools/team/onboarding_quiz_draft

Example arguments for the onboarding_quiz_draft tool, specifying the module_id parameter. The module_id must match the pattern ^[a-zA-Z0-9_-]{1,64}$.

```json
{
  "module_id": "mod_deploy"
}
```

--------------------------------

### Initialize a session with session_init

Source: https://totalmemory.dev/docs/first-day

Resumes a project session by returning the saved summary, next steps, and pitfalls from the previous session.

```text
session_init(project="my-api")
→ summary:    "Migrated auth middleware to JWT"
  next_steps: ["Update OpenAPI spec", "Tell the frontend team"]
  pitfalls:   ["Do not revert migration 0042: dev DB is already migrated"]
```

--------------------------------

### phase_transition Arguments Example

Source: https://totalmemory.dev/docs/tools/phase_transition

Example arguments for the phase_transition tool, showing a task_id, new_phase, artifacts, and notes. Values are illustrative; the keys follow the server's handler.

```json
{
  "task_id": "BILL-142",
  "new_phase": "plan",
  "artifacts": {
    "plan": "docs/rate-limit-plan.md"
  },
  "notes": "Token bucket per API key"
}
```

--------------------------------

### self_error_log Arguments Example

Source: https://totalmemory.dev/docs/tools/self_error_log

Example of the JSON arguments required to call the self_error_log tool.

```json
{
  "description": "Ran migrations against the test DB; expected dev DB",
  "category": "config_error",
  "severity": "medium",
  "fix": "Set DATABASE_URL in .env.local",
  "context": "Adding orders.status column",
  "project": "my-api"
}
```

--------------------------------

### Run health check commands

Source: https://totalmemory.dev/docs/troubleshooting

Commands to diagnose the installation status based on the installation method.

```bash
npx -y total-agent-memory status
```

```bash
npx -y total-agent-memory doctor
```

```bash
bash scripts/diagnose.sh
```

```powershell
.\scripts\diagnose.ps1
```

```bash
pip show total-agent-memory
```

```bash
pipx list
```

--------------------------------

### Install TAM CLI

Source: https://totalmemory.dev/docs/integrations/hermes

Install the TAM CLI tool required for local mode operation.

```bash
pipx install total-agent-memory      # or: uv tool install total-agent-memory
```

--------------------------------

### onboarding_overview

Source: https://totalmemory.dev/docs/tools/team/onboarding_overview

Lists the departments you belong to with their onboarding status, plus the departments whose people you may view or manage. Use it to pick team_id before onboarding_start.

```APIDOC
## onboarding_overview

### Description
Lists the departments you belong to with their onboarding status, plus the departments whose people you may view or manage.

### Method
MCP tool

### Endpoint
onboarding_overview

### Parameters
This tool takes no parameters.

### Request Example
{}

### Response
#### Success Response
- **user** (object) - The current user information.
  - **user_id** (string) - The user's identifier.
  - **display_name** (string) - The user's display name.
  - **org_role** (string) - The user's organization role.
- **teams** (array) - List of departments the user belongs to with onboarding status.
  - **team_id** (string) - The department identifier.
  - **name** (string) - The department name.
  - **role** (string) - The user's role in the department.
  - **has_curriculum** (boolean) - Whether the department has a curriculum.
  - **enrolled_at** (string) - The enrollment timestamp.
  - **title** (string) - The onboarding title.
  - **summary** (object) - Onboarding progress summary.
    - **lessons_completed** (integer) - Number of completed lessons.
    - **lessons_total** (integer) - Total number of lessons.
    - **modules_finished** (integer) - Number of finished modules.
    - **modules_total** (integer) - Total number of modules.
    - **percent** (integer) - Completion percentage.
    - **updated_lessons** (integer) - Number of updated lessons.
- **viewable_teams** (array) - List of departments whose people the user may view.
- **manageable_teams** (array) - List of departments whose people the user may manage.

#### Response Example
{
  "user": {
    "user_id": "dina",
    "display_name": "Dina Developer",
    "org_role": "member"
  },
  "teams": [
    {
      "team_id": "eng",
      "name": "Engineering",
      "role": "editor",
      "has_curriculum": true,
      "enrolled_at": "2026-09-25T09:12:04.118Z",
      "title": "Engineering onboarding",
      "summary": {
        "lessons_completed": 2,
        "lessons_total": 4,
        "modules_finished": 1,
        "modules_total": 2,
        "percent": 50,
        "updated_lessons": 0
      }
    }
  ],
  "viewable_teams": [],
  "manageable_teams": []
}
```

--------------------------------

### Run setup in non-interactive personal mode

Source: https://totalmemory.dev/docs/setup-wizard

Executes the setup wizard for a personal configuration using detected clients and multilingual embeddings.

```bash
tam setup --non-interactive --mode personal --clients detected --embed-preset multilingual \
  --llm openai --llm-api-key-env OPENAI_API_KEY --no-hooks --skills
```
Tokens:
Raw