# Fulcra - a durable, user-owned agent-native context store. Built for bridging the gap between agents and humans

## About

[Fulcra](https://fulcradynamics.com/) is a personal data platform: a context lake where a human collects and stores their real-world data and shares it with their AI agents. The data belongs to the user, not to any single agent, so it persists across sessions, agents, and harnesses. An agent running in Claude, ChatGPT/Codex, Hermes, OpenClaw, a cron job, or a Jupyter notebook can all read and write the same datastore.

What a Fulcra datastore holds:

* **Records of Data Types.** A Data Type describes something a user records; a Record is one saved instance. Fulcra ships a catalog of built-in Data Types, and users (or their agents) can create custom ones with fields of their own. Every Data Type has a Record Type: **Events** (a point or span in time) or **Metrics** (a measurable value over time). Records carry a start time (and an end time for spans), a source chain, and optional tags.
* **Files**, with full version history and restore. Files are a secure object store for anything an agent needs to keep: memory, notes, preferences, task boards, exports, dashboards.
* **Device-collected data**, if the user opts in. The optional [Context by Fulcra](https://apps.apple.com/us/app/context-personal-data-kit/id1633037434) iOS app can sync Apple Health, location, and calendar data into the same datastore in the background.
* **Shares and groups.** Users can share Data Types and files with other Fulcra users, and with groups so every member gets access.

All Records and Files are encrypted at rest. Platform concepts are documented at [docs.fulcradynamics.com/fulcra-platform](https://docs.fulcradynamics.com/fulcra-platform/).

### What agents use Fulcra for

* **Durable memory across harnesses.** Back up an agent's memory, preferences, or working state to Fulcra files, then restore or clone it into a different agent or a fresh session.
* **Structured tracking.** Create a custom Data Type for anything (mood, market data, habits, build times, a project's progress), record values over time, and query them back later.
* **Multi-agent coordination.** Several agents working for the same user share files and records through one datastore and poll `data-updates` to learn what changed since they last looked.
* **Situational awareness.** Combine the user's own records with device data (sleep, workouts, location, calendar) when the user has connected those sources.

### Interactive access for the human

The human explores their data, manages files and shares, and reviews what their agents have written using the [Context Web](https://context.fulcradynamics.com/) app and the Context iOS app.

## Interfaces for agents and code

| Interface | Best for | Where |
|---|---|---|
| **CLI** `fulcra` (run as `uvx fulcra-api`) | Agents with a shell. JSON output, agent-friendly auth. | [CLI docs](https://docs.fulcradynamics.com/cli/) |
| **MCP server** | Agents without a shell (Claude, ChatGPT, Codex, Goose, and other MCP clients). | [MCP docs](https://docs.fulcradynamics.com/mcp/), endpoint `https://mcp.fulcradynamics.com/mcp` |
| **Python library** `fulcra-api` | Code-first agents and notebooks. | [Library docs](https://fulcradynamics.github.io/fulcra-api-python/), [PyPI](https://pypi.org/project/fulcra-api/) |
| **REST API** (the "Life API") | Any HTTP client. OAuth2 bearer tokens. | [REST reference](https://docs.fulcradynamics.com/rest-api/), [OpenAPI spec](https://api.fulcradynamics.com/openapi.json) |

The CLI and the Python library are the same PyPI package (`fulcra-api`, Python 3.11 or newer). The MCP server is open source at [fulcradynamics/fulcra-context-mcp](https://github.com/fulcradynamics/fulcra-context-mcp) and published to PyPI as [`fulcra-context-mcp`](https://pypi.org/project/fulcra-context-mcp/).

## Getting connected

### The fastest agent entry point

If you are an agent reading this: fetch and follow `https://docs.fulcradynamics.com/agent-get-started.txt`. It walks you through connecting, authenticating, and doing something useful in the same session.

### Skills

Install the official skill library to give yourself structured ways to work with Fulcra on your user's behalf:

```shell
npx skills add fulcradynamics/agent-skills
```

Or install just the onboarding skill:

```shell
npx skills add fulcradynamics/agent-skills --skill fulcra-get-started
```

Browse [fulcradynamics/agent-skills](https://github.com/fulcradynamics/agent-skills/) for the full list. Current skills cover getting started, connecting and authenticating, custom tracking and dashboards, agent memory backup and restore, shared workspaces for multiple agents, cross-agent preferences, situational awareness, and importing third-party data exports. Community-contributed skills and use cases live in [fulcradynamics/community-skills](https://github.com/fulcradynamics/community-skills).

### Connect pages per agent platform

Step-by-step connect guides with paste-ready prompts: [Claude](https://fulcradynamics.com/connect/claude), [ChatGPT](https://fulcradynamics.com/connect/chatgpt), [Hermes](https://fulcradynamics.com/connect/hermes), [OpenClaw](https://fulcradynamics.com/connect/openclaw), [Apple Health & MCP](https://fulcradynamics.com/connect/apple-health-mcp). Architectural guidance for agent builders: [fulcradynamics.com/agents](https://fulcradynamics.com/agents).

## Authentication

Every interface uses OAuth2 and never asks the agent to handle a password. The user authorizes in a browser; the agent receives a token.

### CLI (two-step, agent-friendly)

Step 1 returns a URL and code for the user. Step 2 blocks and polls until the user finishes in the browser.

```shell
uvx fulcra-api auth login --get-auth-url
uvx fulcra-api auth login --device-code <device code from step 1>
```

Tokens are cached and refreshed automatically. Interactive humans can just run `uvx fulcra-api auth login`, which opens the browser and completes on its own. For raw HTTP calls, `fulcra auth print-access-token` prints a bearer token.

If `auth login` fails at once, the environment probably has no outbound network access. Tell the user and suggest the MCP connector instead of retrying.

### Python library

`FulcraAPI().authorize()` prints a URL to hand to the user and polls until they approve it (OAuth2 Device Authorization Flow). If it times out, call `authorize()` again for a new URL.

### MCP

Point an OAuth2-capable MCP client at `https://mcp.fulcradynamics.com/mcp` (Streamable HTTP transport). The client prompts the user to log in; the login applies only to that client's session, and the server never exposes the exchanged tokens to the client.

## The core loop

1. **Ask what changed first.** Before re-reading anything, ask Fulcra what was added or updated since you last looked: CLI `uvx fulcra-api data-updates "1 hour"`, MCP tool `get_data_updates`, REST `GET /data/v1/updates`. One call summarizes record ingestion and file changes across the datastore. Pass a user ID to see updates to data another user has shared with you.
2. **Discover before you query.** `uvx fulcra-api catalog` (MCP `get_data_catalog`) lists every Data Type you can query or record, including the user's custom types and types shared with them. `uvx fulcra-api catalog --user-defined` lists just the custom ones, the user's own and those shared with them; add `--recordable` for only the user's own. Filter further with `-c <category>` (for example `base_type`) or `-n <name>`.
3. **Read and write records.** `uvx fulcra-api get-records <DataType> "1 week"` returns JSON lines for a relative window or an explicit start and end. `uvx fulcra-api record <DataType> [value]` records one sample, or pipe JSON lines into it for many. `uvx fulcra-api data-type schema <DataType>` prints the record schema as JSON Schema.
4. **Create your own Data Types.** `uvx fulcra-api data-type create <BaseType> <Name> --description "..."`. For new tracking, use `Event` (something that happens) or `Metric` (a measured number), and pass your own fields as a JSON Schema with `--fields`. The older annotation base types (`MomentAnnotation`, `DurationAnnotation`, `NumericAnnotation`, `ScaleAnnotation`, `BooleanAnnotation`) still work but take no custom fields. Custom types are referenced as `<BaseType>/<UUID>`, for example `Event/642f37c8-67aa-4758-8cc9-9368b47dd766`. `uvx fulcra-api data-type list` lists the ones the user has created.
5. **Use files for anything unstructured.** `uvx fulcra-api file upload|list|stat|download|delete|restore|share`, and `fulcra file download <path> -` to print a file's contents to stdout. Remote paths are always `/`-rooted with forward slashes on every platform.

`uvx fulcra-api --help` and `uvx fulcra-api <command> --help` document every command, including `share`, `group`, and `tag` for sharing data with other users and groups. Most query commands print JSON lines that pipe cleanly into `jq`. If a command or option shown here is missing, `uvx` is running an older cached version: use `uvx fulcra-api@latest`.

### MCP tools

Start with `get_user_info` and `get_data_catalog` to learn what the user has chosen to record, then query specific ranges. `get_data_catalog` with `category="user_defined"` lists the custom Data Types the user and others have created.

* **Datastore:** `get_data_catalog`, `get_records`, `get_time_series`, `record_data`, `create_data_type`, `archive_data_type`, `restore_data_type`, `get_data_updates`
* **Files:** `list_files`, `read_file`, `write_file`, `delete_file`, `restore_file`
* **Device data:** `get_sleep`, `get_workouts`, `get_location_at_time`, `get_location_time_series`, `get_calendars`, `get_calendar_events`
* **Account:** `get_user_info`

All time parameters must include a time zone (ISO 8601). Translate result timestamps to the user's local time zone when known.

### Python example

```python
from fulcra_api.core import FulcraAPI

fulcra = FulcraAPI()
fulcra.authorize()

# What changed in the last day?
updates = fulcra.data_updates("2026-09-09T00:00:00Z", "2026-09-10T00:00:00Z")

# Discover data types (built-in, custom, and shared)
catalog = fulcra.v1_catalog()

# Record a value to a custom Metric data type
fulcra.record_data_type(
    "Metric/642f37c8-67aa-4758-8cc9-9368b47dd766",
    [{"value": 42, "start_time": "2026-09-10T08:00:00Z"}],
    api_version="v1",
)

# Time series for a metric at hourly resolution (returns a pandas DataFrame)
df = fulcra.metric_time_series(
    start_time="2026-09-09T00:00:00-08:00",
    end_time="2026-09-10T00:00:00-08:00",
    metric="StepCount",
    sample_rate=3600,
)
```

Ready-to-run notebooks are in the [demos repository](https://github.com/fulcradynamics/demos), openable directly in Google Colab.

## Running the MCP server locally

The server can also run locally over stdio, for clients that only support stdio or for users who prefer to keep it on their own machine. Run it with `uvx fulcra-context-mcp@latest`.

The easiest hosted setup for Claude Desktop is to add `https://mcp.fulcradynamics.com/mcp` as a remote connector in the Connectors settings. For stdio-only clients, use the `mcp-remote` proxy:

```json
{
    "mcpServers": {
        "fulcra_context": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "https://mcp.fulcradynamics.com/mcp"
            ]
        }
    }
}
```

Fully local server:

```json
{
    "mcpServers": {
        "fulcra_context": {
            "command": "uvx",
            "args": [
                "fulcra-context-mcp@latest"
            ]
        }
    }
}
```

## Device-collected data

When the user has connected sources, the same datastore also holds:

* **Health and biometrics:** sleep stages and cycles, heart rate and HRV, resting heart rate, SpO2, respiratory rate, temperature, steps, energy, workouts, body composition, and more, from Apple Health and devices that feed it (Garmin, Oura, Whoop, CGMs such as Dexcom and Libre).
* **Location:** high-frequency location updates and visit summaries from Apple and Google Maps.
* **Calendar:** calendars and events synced from the phone.

Example time-series metrics: `StepCount`, `HeartRate`, `HeartRateVariabilitySDNN`, `SleepStage`, `ActiveCaloriesBurned`, `RespiratoryRate`, `OxygenSaturation`. Discover the full list with `uvx fulcra-api catalog`.

## Best practices for agents

* **Timestamps are always timezone-aware.** Naive datetimes are a bug. Prefer ISO 8601 with an explicit offset or `Z`.
* **Check `data-updates` before re-reading.** It is the cheapest way to learn whether anything changed.
* **Name things for other agents.** Files and custom Data Types are shared with every agent the user connects. Use descriptive names and paths, and check the catalog and file list before creating duplicates.
* **Files are versioned.** Overwriting a file keeps history; a deleted file or version can be restored. Prefer overwriting a known path over creating many similar files.
* **Choose a sensible `sample_rate`** for time series: 3600 seconds for daily overviews, 60 to 300 seconds for detail.
* **Sleep spans midnight.** A night's sleep starts on day N and ends on day N+1, so extend the query range.
* **Correlate across domains.** The value of one datastore is combining streams: an agent's own records with calendar events, or user-logged events with device data.

## Support

* **Email:** [support@fulcradynamics.com](mailto:support@fulcradynamics.com)
* **Discord:** [Fulcra Discord](https://discord.com/invite/aunahVEnPU)
* **GitHub:** [github.com/fulcradynamics](https://github.com/fulcradynamics)
* **Live web chat:** available on fulcradynamics.com
* **Changelog:** [docs.fulcradynamics.com/changelog](https://docs.fulcradynamics.com/changelog/)

## Official domains

* fulcradynamics.com
* context.fulcradynamics.com
* docs.fulcradynamics.com
* api.fulcradynamics.com
* mcp.fulcradynamics.com
* fulcra.ai