Skip to content

Commit 4337354

Browse files
Alan-TheGentlemanAlan-TheGentleman
authored
docs: bring docs up to date with recently merged features (#436)
- ENGRAM_HTTP_TOKEN: document optional Bearer auth for local HTTP server (requireAuth middleware, protected routes, constant-time compare, zero-config default when unset) - scope=personal cross-project: document that mem_search and mem_context clear the project filter when scope=personal without explicit project - global scope: add 'global' to every scope enum in DOCS.md, ARCHITECTURE.md, and HTTP API docs - ENGRAM_TIMEZONE: document IANA timezone for TUI/dashboard display - engram delete --hard: add row to CLI reference tables in README.md and ARCHITECTURE.md (already in printUsage) - TUI 'c' copy: document copy-to-clipboard (OSC 52) in DOCS.md Navigation and README.md Terminal UI sections - ENGRAM_CLOUD_ALLOWED_PROJECTS '*' wildcard: document in DOCS.md cloud env table, README.md cloud section, and ARCHITECTURE.md - Pi npmCommand mise pinning: document ensurePiNpmCommand auto-pin behavior in plugin/pi/README.md and docs/AGENT-SETUP.md - Prior debt: expand DOCS.md env table from 3 rows to full list synced with printUsage; add doctor, conflicts, delete, projects prune to CLI reference tables in README.md and ARCHITECTURE.md; sync printUsage env block (add ENGRAM_HTTP_TOKEN, ENGRAM_TIMEZONE, ENGRAM_AGENT_CLI, ENGRAM_CLOUD_AUTOSYNC, ENGRAM_CLOUD_SERVER; fix indentation) Closes #435
1 parent 8dccc52 commit 4337354

6 files changed

Lines changed: 84 additions & 20 deletions

File tree

‎DOCS.md‎

Lines changed: 29 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -133,8 +133,8 @@ Engram is local-first: local SQLite is authoritative; cloud features are optiona
133133
### Observations
134134

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

162162
### Context
163163

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

166166
### Passive Capture
167167

@@ -453,11 +453,24 @@ Response:
453453

454454
### Environment Variables
455455

456-
| Variable | Description | Default |
457-
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
458-
| `ENGRAM_DATA_DIR` | Override data directory | `~/.engram` |
459-
| `ENGRAM_PORT` | Override HTTP server port | `7437` |
460-
| `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 |
456+
| Variable | Description | Default |
457+
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
458+
| `ENGRAM_DATA_DIR` | Override data directory | `~/.engram` |
459+
| `ENGRAM_PORT` | Override HTTP server port | `7437` |
460+
| `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 |
461+
| `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) |
462+
| `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 |
463+
| `ENGRAM_AGENT_CLI` | LLM runner name used by `engram conflicts scan --semantic` and the HTTP `/conflicts/scan` endpoint. Accepted values: `claude`, `opencode`. | (unset) |
464+
| `ENGRAM_CLOUD_AUTOSYNC` | Set to `1` to enable background autosync. Requires `ENGRAM_CLOUD_TOKEN` and `ENGRAM_CLOUD_SERVER` to also be set. | (unset — disabled) |
465+
| `ENGRAM_CLOUD_SERVER` | Cloud server URL used by the autosync manager and `engram sync --cloud`. | (unset) |
466+
| `ENGRAM_DATABASE_URL` | Postgres DSN for `engram cloud serve`. | (unset) |
467+
| `ENGRAM_CLOUD_HOST` | Bind host for `engram cloud serve`. | `127.0.0.1` |
468+
| `ENGRAM_CLOUD_MAX_PUSH_BYTES` | Max cloud push payload bytes. | `8388608` |
469+
| `ENGRAM_CLOUD_TOKEN` | Bearer token required in authenticated `engram cloud serve` mode. | (unset) |
470+
| `ENGRAM_CLOUD_INSECURE_NO_AUTH` | Set to `1` for local insecure cloud serve (no auth). Cannot be combined with `ENGRAM_CLOUD_TOKEN`. | (unset) |
471+
| `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) |
472+
| `ENGRAM_JWT_SECRET` | Required in authenticated cloud serve mode. Must be explicitly set to a non-default value. | (unset) |
473+
| `ENGRAM_CLOUD_ADMIN` | Optional admin-only dashboard token in authenticated cloud serve mode. Ignored/rejected in insecure mode. | (unset) |
461474

462475
### Conflict Audit CLI (admin)
463476

@@ -549,7 +562,7 @@ Cloud runtime envs for `engram cloud serve`:
549562
| `ENGRAM_PORT` | no | Runtime port (default `8080`) |
550563
| `ENGRAM_CLOUD_HOST` | no | Bind host (default `127.0.0.1`; use `0.0.0.0` for containers) |
551564
| `ENGRAM_CLOUD_MAX_PUSH_BYTES` | no | Max chunk/mutation push request body bytes (default `8388608`) |
552-
| `ENGRAM_CLOUD_ALLOWED_PROJECTS` | yes | Comma-separated allowlist; always required (authenticated + insecure modes) |
565+
| `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. |
553566
| `ENGRAM_CLOUD_TOKEN` | yes (authenticated mode) | Enables bearer auth mode |
554567
| `ENGRAM_JWT_SECRET` | yes (authenticated mode) | Must be explicitly set and non-default when token mode is enabled |
555568
| `ENGRAM_CLOUD_INSECURE_NO_AUTH` | no | Set to `1` only for local insecure mode; cannot be combined with `ENGRAM_CLOUD_TOKEN` |
@@ -762,6 +775,8 @@ Search persistent memory across all sessions. Supports FTS5 full-text search wit
762775

763776
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.
764777

778+
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).
779+
765780
When an observation has judged relations in `memory_relations`, the result entry includes annotation lines immediately after the title/content block:
766781

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

782797
- **title**: Short, searchable (e.g. "JWT auth middleware")
783798
- **type**: `decision` | `architecture` | `bugfix` | `pattern` | `config` | `discovery` | `learning`
784-
- **scope**: `project` (default) | `personal`
799+
- **scope**: `project` (default) | `personal` | `global`
785800
- **topic_key**: optional canonical topic id (e.g. `architecture/auth-model`) used to upsert evolving memories
786801
- **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`.
787802
- **content**: Structured with `**What**`, `**Why**`, `**Where**`, `**Learned**`; required unless the legacy `observation` alias is provided
@@ -811,6 +826,8 @@ When called in the same MCP process, this also feeds process-local current promp
811826

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

829+
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).
830+
814831
### mem_stats
815832

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

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

11371154
- `j/k` or arrow keys — Navigate lists
11381155
- `Enter` — Select / drill into detail
1156+
- `c` — Copy observation content to clipboard (OSC 52; works in search results, recent list, detail, and session views)
11391157
- `t` — View timeline for selected observation
11401158
- `s` or `/` — Quick search from any screen
11411159
- `Esc` or `q` — Go back / quit

‎README.md‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,7 @@ engram tui
106106
<img src="assets/tui-search.png" alt="TUI Search Results" width="400" />
107107
</p>
108108

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

111111
## Git Sync
112112

@@ -137,6 +137,7 @@ engram sync --cloud --project smoke-project
137137
```
138138

139139
Cloud mode is always project-scoped (`--project` is required; `engram sync --cloud --all` is intentionally blocked).
140+
`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.
140141
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.
141142
For blocked cloud sync, `transport_failed`, or legacy session directory repair, see [Engram Cloud Troubleshooting](docs/engram-cloud/troubleshooting.md).
142143
If cloud sync stays blocked after `doctor`/`repair`, download the rescue helper and run the recommended exported-row repair:
@@ -306,19 +307,35 @@ Your production engram is fully untouched throughout.
306307
| `engram tui` | Launch terminal UI |
307308
| `engram search <query>` | Search memories |
308309
| `engram save <title> <msg>` | Save a memory |
310+
| `engram delete <obs_id>` | Delete an observation (soft by default; `--hard` removes permanently) |
309311
| `engram timeline <obs_id>` | Chronological context |
310312
| `engram context [project]` | Recent session context |
311313
| `engram stats` | Memory statistics |
312314
| `engram export [file]` | Export to JSON |
313315
| `engram import <file>` | Import from JSON |
314316
| `engram sync` | Git sync export/import |
317+
| `engram conflicts <sub>` | Inspect and manage memory conflict relations |
318+
| `engram doctor` | Run read-only operational diagnostics |
315319
| `engram cloud <subcommand>` | Opt-in cloud config/status/enrollment + cloud runtime (`serve`) |
316320
| `engram projects list\|consolidate\|prune` | Manage project names |
317321
| `engram obsidian-export` | Export to Obsidian vault (beta) |
318322
| `engram version` | Show version |
319323

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

326+
### Key Environment Variables
327+
328+
| Variable | Description | Default |
329+
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------- |
330+
| `ENGRAM_DATA_DIR` | Override data directory | `~/.engram` |
331+
| `ENGRAM_PORT` | Override HTTP server port | `7437` |
332+
| `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) |
333+
| `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 |
334+
| `ENGRAM_CLOUD_AUTOSYNC` | Set to `1` to enable background autosync (also requires `ENGRAM_CLOUD_TOKEN` + `ENGRAM_CLOUD_SERVER`). | (unset) |
335+
| `ENGRAM_CLOUD_ALLOWED_PROJECTS` | Comma-separated project allowlist for `engram cloud serve`. Use `*` to allow all projects. | (unset) |
336+
337+
Full environment variable reference → [DOCS.md#environment-variables](DOCS.md#environment-variables)
338+
322339
## Documentation
323340

324341
| Doc | Description |

0 commit comments

Comments
 (0)