Skip to content

docs: document recent env vars, CLI commands, scopes, and TUI keybindings #436

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Alan-TheGentleman merged 1 commit into from
May 27, 2026
Merged

docs: document recent env vars, CLI commands, scopes, and TUI keybindings #436

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 29 additions & 11 deletions DOCS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,8 +133,8 @@ Engram is local-first: local SQLite is authoritative; cloud features are optiona
### Observations

- `POST /observations` — Add observation. Body: `{session_id, type, title, content, tool_name?, project?, scope?, topic_key?}`
- `GET /observations` — Recent observations compatibility endpoint. Query: `?project=X&scope=project|personal&limit=N&sort=created_at:desc`
- `GET /observations/recent` — Recent observations. Query: `?project=X&scope=project|personal&limit=N`
- `GET /observations` — Recent observations compatibility endpoint. Query: `?project=X&scope=project|personal|global&limit=N&sort=created_at:desc`
- `GET /observations/recent` — Recent observations. Query: `?project=X&scope=project|personal|global&limit=N`
- `GET /observations/{id}` — Get single observation by ID
- `PATCH /observations/{id}` — Update fields. Body: `{title?, content?, type?, project?, scope?, topic_key?}`
- `DELETE /observations/{id}` — Delete observation (`?hard=true` for hard delete, soft delete by default)
Expand All @@ -161,7 +161,7 @@ Engram is local-first: local SQLite is authoritative; cloud features are optiona

### Context

- `GET /context` — Formatted context. Query: `?project=X&scope=project|personal`
- `GET /context` — Formatted context. Query: `?project=X&scope=project|personal|global`

### Passive Capture

Expand Down Expand Up @@ -453,11 +453,24 @@ Response:

### Environment Variables

| Variable | Description | Default |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `ENGRAM_DATA_DIR` | Override data directory | `~/.engram` |
| `ENGRAM_PORT` | Override HTTP server port | `7437` |
| `ENGRAM_PROJECT` | Default project for `engram serve` `GET /sync/status` when no `project` query param is supplied. When unset, cwd detection is used as the fallback. | cwd-detected project |
| Variable | Description | Default |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `ENGRAM_DATA_DIR` | Override data directory | `~/.engram` |
| `ENGRAM_PORT` | Override HTTP server port | `7437` |
| `ENGRAM_PROJECT` | Default project for `engram serve` `GET /sync/status` when no `project` query param is supplied. When unset, cwd detection is used as the fallback. | cwd-detected project |
| `ENGRAM_HTTP_TOKEN` | Optional Bearer auth for the local HTTP server. When set, the following routes require `Authorization: Bearer <token>`: `DELETE /sessions/{id}`, `DELETE /observations/{id}`, `DELETE /prompts/{id}`, `GET /export`, `POST /import`, `POST /projects/migrate`. Comparison is constant-time. Token is read at request time (no restart needed). When unset, all routes are open (zero-config default). | (unset — open) |
| `ENGRAM_TIMEZONE` | Timezone for timestamp display in the TUI and cloud dashboard. Accepts any IANA zone name (e.g. `America/New_York`, `Europe/Berlin`). Falls back to system local time when unset or invalid. | system local |
| `ENGRAM_AGENT_CLI` | LLM runner name used by `engram conflicts scan --semantic` and the HTTP `/conflicts/scan` endpoint. Accepted values: `claude`, `opencode`. | (unset) |
| `ENGRAM_CLOUD_AUTOSYNC` | Set to `1` to enable background autosync. Requires `ENGRAM_CLOUD_TOKEN` and `ENGRAM_CLOUD_SERVER` to also be set. | (unset — disabled) |
| `ENGRAM_CLOUD_SERVER` | Cloud server URL used by the autosync manager and `engram sync --cloud`. | (unset) |
| `ENGRAM_DATABASE_URL` | Postgres DSN for `engram cloud serve`. | (unset) |
| `ENGRAM_CLOUD_HOST` | Bind host for `engram cloud serve`. | `127.0.0.1` |
| `ENGRAM_CLOUD_MAX_PUSH_BYTES` | Max cloud push payload bytes. | `8388608` |
| `ENGRAM_CLOUD_TOKEN` | Bearer token required in authenticated `engram cloud serve` mode. | (unset) |
| `ENGRAM_CLOUD_INSECURE_NO_AUTH` | Set to `1` for local insecure cloud serve (no auth). Cannot be combined with `ENGRAM_CLOUD_TOKEN`. | (unset) |
| `ENGRAM_CLOUD_ALLOWED_PROJECTS` | Comma-separated project allowlist enforced by `engram cloud serve`. Required in both token-auth and insecure modes. Use `*` to allow all projects (dev/internal deploys) — bypasses per-project name enforcement while still requiring a non-empty project on each request. | (unset) |
| `ENGRAM_JWT_SECRET` | Required in authenticated cloud serve mode. Must be explicitly set to a non-default value. | (unset) |
| `ENGRAM_CLOUD_ADMIN` | Optional admin-only dashboard token in authenticated cloud serve mode. Ignored/rejected in insecure mode. | (unset) |

### Conflict Audit CLI (admin)

Expand Down Expand Up @@ -549,7 +562,7 @@ Cloud runtime envs for `engram cloud serve`:
| `ENGRAM_PORT` | no | Runtime port (default `8080`) |
| `ENGRAM_CLOUD_HOST` | no | Bind host (default `127.0.0.1`; use `0.0.0.0` for containers) |
| `ENGRAM_CLOUD_MAX_PUSH_BYTES` | no | Max chunk/mutation push request body bytes (default `8388608`) |
| `ENGRAM_CLOUD_ALLOWED_PROJECTS` | yes | Comma-separated allowlist; always required (authenticated + insecure modes) |
| `ENGRAM_CLOUD_ALLOWED_PROJECTS` | yes | Comma-separated allowlist; always required (authenticated + insecure modes). Use `*` to allow all projects (dev/internal deploys) — bypasses per-project name enforcement while still requiring a non-empty project on each request. |
| `ENGRAM_CLOUD_TOKEN` | yes (authenticated mode) | Enables bearer auth mode |
| `ENGRAM_JWT_SECRET` | yes (authenticated mode) | Must be explicitly set and non-default when token mode is enabled |
| `ENGRAM_CLOUD_INSECURE_NO_AUTH` | no | Set to `1` only for local insecure mode; cannot be combined with `ENGRAM_CLOUD_TOKEN` |
Expand Down Expand Up @@ -762,6 +775,8 @@ Search persistent memory across all sessions. Supports FTS5 full-text search wit

Set `all_projects: true` to search across every project instead of the resolved one. This bypasses project detection entirely and ignores the `project` argument, so an agent can recall a decision logged elsewhere without knowing the project key. The response envelope reports `project_source: "all_projects"` and an empty `project` to reflect the cross-project scope.

Scope values accepted by the `scope` parameter: `project` (default), `personal`, `global`. When `scope: personal` is passed without an explicit `project` override, the project filter is cleared and personal observations are searched across all projects (cross-project personal scope).

When an observation has judged relations in `memory_relations`, the result entry includes annotation lines immediately after the title/content block:

```
Expand All @@ -781,7 +796,7 @@ Save structured observations. The tool description teaches agents the format:

- **title**: Short, searchable (e.g. "JWT auth middleware")
- **type**: `decision` | `architecture` | `bugfix` | `pattern` | `config` | `discovery` | `learning`
- **scope**: `project` (default) | `personal`
- **scope**: `project` (default) | `personal` | `global`
- **topic_key**: optional canonical topic id (e.g. `architecture/auth-model`) used to upsert evolving memories
- **capture_prompt**: optional boolean, default `true`; when current prompt context is available in the same MCP process for the same project/session, Engram best-effort records it alongside the observation. If that process-local context is unavailable or prompt capture fails, `mem_save` still succeeds. Automated pipeline saves such as SDD artifacts should pass `false`.
- **content**: Structured with `**What**`, `**Why**`, `**Where**`, `**Learned**`; required unless the legacy `observation` alias is provided
Expand Down Expand Up @@ -811,6 +826,8 @@ When called in the same MCP process, this also feeds process-local current promp

Get recent memory context from previous sessions — shows sessions, prompts, and observations, with optional scope filtering for observations.

Scope values accepted by the `scope` parameter: `project` (default), `personal`, `global`. When `scope: personal` is passed without an explicit `project` override, the project filter is cleared and personal observations are returned across all projects (cross-project personal scope).

### mem_stats

Show memory system statistics — sessions, observations, prompts, projects.
Expand Down Expand Up @@ -919,7 +936,7 @@ Format for `mem_save`:

- **title**: Verb + what — short, searchable (e.g. "Fixed N+1 query in UserList", "Chose Zustand over Redux")
- **type**: `bugfix` | `decision` | `architecture` | `discovery` | `pattern` | `config` | `preference`
- **scope**: `project` (default) | `personal`
- **scope**: `project` (default) | `personal` | `global`
- **topic_key** (optional, recommended for evolving decisions): stable key like `architecture/auth-model`
- **content**:
```
Expand Down Expand Up @@ -1136,6 +1153,7 @@ Interactive Bubbletea-based terminal UI. Launch with `engram tui`.

- `j/k` or arrow keys — Navigate lists
- `Enter` — Select / drill into detail
- `c` — Copy observation content to clipboard (OSC 52; works in search results, recent list, detail, and session views)
- `t` — View timeline for selected observation
- `s` or `/` — Quick search from any screen
- `Esc` or `q` — Go back / quit
Expand Down
19 changes: 18 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ engram tui
<img src="assets/tui-search.png" alt="TUI Search Results" width="400" />
</p>

**Navigation**: `j/k` vim keys, `Enter` to drill in, `/` to search, `Esc` back. Catppuccin Mocha theme.
**Navigation**: `j/k` vim keys, `Enter` to drill in, `c` to copy content to clipboard (OSC 52), `/` to search, `Esc` back. Catppuccin Mocha theme.

## Git Sync

Expand Down Expand Up @@ -137,6 +137,7 @@ engram sync --cloud --project smoke-project
```

Cloud mode is always project-scoped (`--project` is required; `engram sync --cloud --all` is intentionally blocked).
`ENGRAM_CLOUD_ALLOWED_PROJECTS` is required for `engram cloud serve` in both token-auth and insecure modes. Set it to `*` to allow all projects (useful for dev/internal deploys) — this bypasses per-project name enforcement while still requiring a non-empty project on each request.
Known repairable cloud sync/upsert/canonicalization failures keep the original error visible and recommend the explicit `doctor`/`repair` flow below; Engram never auto-applies repair from sync or autosync.
For blocked cloud sync, `transport_failed`, or legacy session directory repair, see [Engram Cloud Troubleshooting](docs/engram-cloud/troubleshooting.md).
If cloud sync stays blocked after `doctor`/`repair`, download the rescue helper and run the recommended exported-row repair:
Expand Down Expand Up @@ -306,19 +307,35 @@ Your production engram is fully untouched throughout.
| `engram tui` | Launch terminal UI |
| `engram search <query>` | Search memories |
| `engram save <title> <msg>` | Save a memory |
| `engram delete <obs_id>` | Delete an observation (soft by default; `--hard` removes permanently) |
| `engram timeline <obs_id>` | Chronological context |
| `engram context [project]` | Recent session context |
| `engram stats` | Memory statistics |
| `engram export [file]` | Export to JSON |
| `engram import <file>` | Import from JSON |
| `engram sync` | Git sync export/import |
| `engram conflicts <sub>` | Inspect and manage memory conflict relations |
| `engram doctor` | Run read-only operational diagnostics |
| `engram cloud <subcommand>` | Opt-in cloud config/status/enrollment + cloud runtime (`serve`) |
| `engram projects list\|consolidate\|prune` | Manage project names |
| `engram obsidian-export` | Export to Obsidian vault (beta) |
| `engram version` | Show version |

Full CLI with all flags → [docs/ARCHITECTURE.md#cli-reference](docs/ARCHITECTURE.md#cli-reference)

### Key Environment Variables

| Variable | Description | Default |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------- |
| `ENGRAM_DATA_DIR` | Override data directory | `~/.engram` |
| `ENGRAM_PORT` | Override HTTP server port | `7437` |
| `ENGRAM_HTTP_TOKEN` | Optional Bearer auth for local HTTP server. When set, destructive and export routes require `Authorization: Bearer <token>`. Unset = open (zero-config default). | (unset) |
| `ENGRAM_TIMEZONE` | Timezone for timestamp display in TUI and cloud dashboard (e.g. `America/New_York`). Falls back to system local when unset or invalid. | system local |
| `ENGRAM_CLOUD_AUTOSYNC` | Set to `1` to enable background autosync (also requires `ENGRAM_CLOUD_TOKEN` + `ENGRAM_CLOUD_SERVER`). | (unset) |
| `ENGRAM_CLOUD_ALLOWED_PROJECTS` | Comma-separated project allowlist for `engram cloud serve`. Use `*` to allow all projects. | (unset) |

Full environment variable reference → [DOCS.md#environment-variables](DOCS.md#environment-variables)

## Documentation

| Doc | Description |
Expand Down
Loading
Loading