Configuration

Configuration is minimal. Two environment variables connect the MCP server; everything else has sensible defaults.

Environment Variables

Variable	Description	Required
`AMFS_HTTP_URL`	Your SenseLab API URL — `https://amfs-login.sense-lab.ai` for SenseLab	Yes
`AMFS_API_KEY`	Your API key (from Dashboard → Settings → API Keys)	Yes
`AMFS_AGENT_ID`	Agent identity for headless contexts — CI, scripts, and servers	No

export AMFS_HTTP_URL="https://amfs-login.sense-lab.ai"
export AMFS_API_KEY="<your-api-key>"

AMFS_HTTP_URL is the API host, not the dashboard. SenseLab accounts point at https://amfs-login.sense-lab.ai; the dashboard you log into at amfs.sense-lab.ai will not serve API requests. Self-hosted deployments point at their own API host.

Who reads these

This is the part worth getting right, because the two surfaces behave differently:

Surface	Behaviour
MCP server	Reads both variables and builds the HTTP connection for you. Nothing else to configure
Python and TypeScript SDKs	Ignore them. You must pass an `HttpAdapter` explicitly, as shown below

Setting the environment variables alone will not connect the SDKs. Without an adapter, Python writes to .amfs/ in your working directory and TypeScript writes to memory — the calls succeed, and nothing reaches your account.

If AMFS_HTTP_URL is set but amfs-adapter-http isn’t installed, the MCP server logs a warning and quietly falls back to local storage, so install it alongside the server when you’re wiring things up by hand.

SDK Options

When using the Python SDK directly, pass options to the constructor:

import os

from amfs import AgentMemory
from amfs_adapter_http import HttpAdapter

mem = AgentMemory(
    agent_id="checkout-agent",
    adapter=HttpAdapter(
        base_url=os.environ["AMFS_HTTP_URL"],
        api_key=os.environ["AMFS_API_KEY"],
    ),
    decay_half_life_days=30.0,
)

Parameter	Type	Description
`agent_id`	`str`	Identity for this agent (required)
`adapter`	`AdapterABC`	Where memory is stored. Pass an `HttpAdapter` to reach your account; defaults to a filesystem adapter at `.amfs/`
`session_id`	`str`	Session identifier; auto-generated if omitted
`config_path`	`Path`	Load adapter settings from a config file instead of passing one
`ttl_sweep_interval`	`float`	Seconds between TTL sweep runs
`decay_half_life_days`	`float`	Confidence decay half-life in days
`conflict_policy`	`ConflictPolicy`	How to handle concurrent write conflicts

Install the adapter with pip install amfs-adapter-http. The Python and TypeScript guides cover the rest of the surface.

Agent Identity

Agents are identified by their agent_id. This determines:

Who gets credit for writes (provenance)
What shows up in the Dashboard
How recall() and my_entries() scope results

MCP agents should call amfs_set_identity at the start of each session. Without it, identity is auto-detected from the environment, in this order:

Checked in order	Detected ID
`CURSOR_SESSION_ID` or `VSCODE_PID` present	`cursor/<username>`
`CLAUDE_CODE_SESSION` present	`claude-code/<username>`
`AMFS_AGENT_ID` set	value of `AMFS_AGENT_ID`
Nothing matched	`agent/<username>`

An IDE signal beats AMFS_AGENT_ID, so the variable does not rename an agent running inside Cursor or Claude Code. That is deliberate: it stops a server-side AMFS_AGENT_ID inherited by your shell from relabelling your local sessions. To name an agent in an IDE, call amfs_set_identity.

SDK and REST clients pass agent_id in the constructor or header.

Scoped API Keys

API keys can be restricted to specific entity paths and permissions:

amfs_sk_live_abc123  →  checkout-service/**  [READ_WRITE]
                        shared/patterns/*     [READ]

Create and manage scoped keys in Dashboard → Settings → API Keys. Use the narrowest scope that works — one key per agent or service.

Namespaces

Namespaces isolate memory between environments. Entries in different namespaces don’t see each other. Namespaces are managed through the Dashboard. The default namespace is default.

Next Steps

Quick Start

Write, read, and search memory.

MCP Setup

Connect your IDE to SenseLab.

Core Concepts

How SenseLab works under the hood.

Environment Variables

Full reference with all options.

Product

Getting Started

Guides

Self-Hosting

Core Concepts

Pro Features

Environment Variables

Who reads these

SDK Options

Agent Identity

Scoped API Keys

Namespaces

Next Steps

Quick Start

MCP Setup

Core Concepts

Environment Variables

​Environment Variables

​Who reads these

​SDK Options

​Agent Identity

​Scoped API Keys

​Namespaces

​Next Steps

Quick Start

MCP Setup

Core Concepts

Environment Variables

Environment Variables

Who reads these

SDK Options

Agent Identity

Scoped API Keys

Namespaces

Next Steps