@cerefox/memory 0.9.10 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/dist/bin/cerefox.js +367 -169
  2. package/dist/frontend/assets/{index-AFUS7_0T.js → index-DVXDQ7__.js} +2 -2
  3. package/dist/frontend/assets/{index-AFUS7_0T.js.map → index-DVXDQ7__.js.map} +1 -1
  4. package/dist/frontend/index.html +1 -1
  5. package/docs/guides/quickstart.md +5 -0
  6. package/docs/guides/setup-local.md +85 -120
  7. package/package.json +1 -1
package/dist/frontend/index.html CHANGED
@@ -15,7 +15,7 @@
15
15
  href="https://fonts.googleapis.com/css2?family=Geist:wght@300;400;500;600;700&display=swap"
16
16
  />
17
17
  <title>Cerefox</title>
18
- <script type="module" crossorigin src="/app/assets/index-AFUS7_0T.js"></script>
18
+ <script type="module" crossorigin src="/app/assets/index-DVXDQ7__.js"></script>
19
19
  <link rel="stylesheet" crossorigin href="/app/assets/index-Asx5wD7g.css">
20
20
  </head>
21
21
  <body>
package/docs/guides/quickstart.md CHANGED
@@ -8,6 +8,11 @@ install and setup below is about 5 minutes.
8
8
  > **Upgrading from an earlier version?** See [`upgrading.md`](upgrading.md)
9
9
  > for migration steps instead.
10
10
 
11
+ > **Want no cloud at all?** Cerefox also runs **fully local** — one Docker
12
+ > container, no Supabase account, no Node/Bun on the host. See
13
+ > [`setup-local.md`](setup-local.md). This quickstart covers the hosted-Supabase
14
+ > path.
15
+
11
16
  ---
12
17
 
13
18
  ## Prerequisites
package/docs/guides/setup-local.md CHANGED
@@ -1,184 +1,149 @@
1
- # Local Setup Guide
1
+ # Local / Self-Hosted Setup (Docker)
2
2
 
3
- Run the Cerefox web server and database on your own machine using Docker for Postgres+pgvector. Embeddings use the OpenAI API — an `OPENAI_API_KEY` is required even for local setups.
3
+ Run Cerefox **fully on your own machine** — no hosted Supabase, no cloud database. One
4
+ Docker container bundles everything: Postgres + pgvector, the PostgREST Data API, and the
5
+ Cerefox web server. You get the same web UI, CLI, and MCP server as the cloud setup.
4
6
 
5
- This guide is aimed at **contributors** who want a fully local stack (no hosted Supabase). End users on a hosted Supabase project should follow [`quickstart.md`](quickstart.md) instead.
7
+ > **Embeddings still use the OpenAI API.** An `OPENAI_API_KEY` is required even for a
8
+ > local setup (the database and web server are local; embedding generation is not). A
9
+ > fully offline embedder is on the roadmap.
6
10
 
7
- ---
8
-
9
- ## Prerequisites
11
+ ## Cloud vs. Local — pick one
10
12
 
11
- - Docker and Docker Compose
12
- - **Node.js 20+** or **Bun 1.0+** (the CLI runtime)
13
- - An OpenAI API key (for embeddings — [platform.openai.com/api-keys](https://platform.openai.com/api-keys))
14
-
15
- > The Python implementation is legacy and slated for removal in a future release; only the Python MCP server remains as a fallback. `uv` is only needed if you intend to run that fallback (`uv run cerefox mcp`).
16
-
17
- ---
13
+ Cerefox has two independent "worlds". Most people run **one or the other**:
18
14
 
19
- ## Step 1 — Clone and install
15
+ | | Cloud / Supabase | **Local / self-hosted (this guide)** |
16
+ |---|---|---|
17
+ | Install | `curl … install.sh \| sh` (npm) | `curl … install-local.sh \| sh` (Docker) |
18
+ | Command | `cerefox` | `cerefox-local` |
19
+ | Backend | hosted Supabase | a Docker container on your machine |
20
+ | Host runtime | Node/Bun | **Docker only** |
20
21
 
21
- ```bash
22
- git clone https://github.com/fstamatelopoulos/cerefox.git
23
- cd cerefox
24
- bun install
25
- ```
22
+ The two never collide — different installer, different command name — so even if you run
23
+ both, your cloud `~/.cerefox/.env` is never touched by the local installer.
26
24
 
27
25
  ---
28
26
 
29
- ## Step 2 — Start Postgres with pgvector
30
-
31
- The included `docker-compose.yml` spins up a Postgres 16 instance with the pgvector extension pre-installed:
32
-
33
- ```bash
34
- docker compose up -d postgres
35
- ```
27
+ ## Prerequisites
36
28
 
37
- Default connection details (overridable in `.env`):
29
+ - **Docker** (Docker Desktop, or [Colima](https://github.com/abiosoft/colima): `colima start`).
30
+ - An **OpenAI API key** — [platform.openai.com/api-keys](https://platform.openai.com/api-keys).
38
31
 
39
- | Setting | Default |
40
- |---------|---------|
41
- | Host | `localhost` |
42
- | Port | `5432` |
43
- | User | `cerefox` |
44
- | Password | `cerefox` |
45
- | Database | `cerefox` |
32
+ That's it. No Node, Bun, Postgres, or repo clone needed.
46
33
 
47
34
  ---
48
35
 
49
- ## Step 3 — Create a `.env` file
36
+ ## Step 1 — Install
50
37
 
51
38
  ```bash
52
- cp .env.example .env
39
+ OPENAI_API_KEY=sk-... sh -c "$(curl -fsSL https://github.com/fstamatelopoulos/cerefox/releases/latest/download/install-local.sh)"
53
40
  ```
54
41
 
55
- Edit `.env` for local Docker:
42
+ This pulls the published multi-arch image (`amd64` + `arm64`), starts the container, and
43
+ installs a `cerefox-local` command (symlinked into `~/.local/bin`). Pick a different port
44
+ with `PORT=8017 …`.
56
45
 
57
- ```env
58
- # Local Postgres (Docker)
59
- CEREFOX_DATABASE_URL=postgresql://cerefox:cerefox@localhost:5432/cerefox
46
+ > If the installer warns that `~/.local/bin` isn't on your `PATH`, add it:
47
+ > ```bash
48
+ > echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
49
+ > ```
60
50
 
61
- # For local-only use, Supabase keys are not required.
62
- # The web UI and CLI will work without them if you skip the Supabase MCP integration.
63
- CEREFOX_SUPABASE_URL=
64
- CEREFOX_SUPABASE_KEY=
51
+ The web UI is now at **http://localhost:8000/app/** (or your chosen port).
65
52
 
66
- # OpenAI API key for embeddings (text-embedding-3-small)
67
- OPENAI_API_KEY=sk-...
68
- ```
53
+ **How the credential works:** the container generates its own JWT secret on first boot and
54
+ mints the access token internally — the token never leaves the container. The only secret
55
+ stored on your host is `OPENAI_API_KEY` (in `~/.cerefox/local/.env`), so `upgrade` can
56
+ re-supply it.
69
57
 
70
58
  ---
71
59
 
72
- ## Step 4 — Deploy the schema
73
-
74
- ```bash
75
- bun scripts/db_deploy.ts
76
- ```
77
-
78
- This creates all tables, indexes, and RPC functions. Run with `--dry-run` to preview SQL without executing.
60
+ ## Step 2 — Use the CLI
79
61
 
80
- To start fresh:
62
+ `cerefox-local` runs the same commands as the cloud `cerefox`, but against your local
63
+ container:
81
64
 
82
65
  ```bash
83
- bun scripts/db_deploy.ts --reset # drops all cerefox_ tables first (typed-`yes` guard)
66
+ cerefox-local status # is it running? what URL?
67
+ cerefox-local document ingest my-notes.md --project-name personal
68
+ cerefox-local search "what did I write about planning?"
69
+ cerefox-local document list
84
70
  ```
85
71
 
86
- > End users on a hosted Supabase project use `cerefox server deploy` instead (no clone). The `bun scripts/db_*.ts` scripts are the low-level contributor path.
72
+ KB verbs (`search`, `document`, `project`, `metadata`, `audit`, `config`, `guides`, `mcp`)
73
+ run inside the container; lifecycle verbs run on the host (next section).
87
74
 
88
75
  ---
89
76
 
90
- ## Step 5 — Verify the setup
77
+ ## Step 3 — Connect an AI agent (MCP)
91
78
 
92
79
  ```bash
93
- bun scripts/db_migrate.ts --status
80
+ cerefox-local configure-agent
94
81
  ```
95
82
 
96
- You should see the schema reported as up to date with all migrations applied.
83
+ If the `claude` CLI is present this registers an MCP server named `cerefox-local` with
84
+ Claude Code automatically. Otherwise it prints the snippet to add to your client — the MCP
85
+ command is simply `cerefox-local mcp` (stdio), which the client launches per session. The
86
+ client never needs a token; the container holds it.
97
87
 
98
88
  ---
99
89
 
100
- ## Step 6 — Ingest your first document
101
-
102
- ```bash
103
- # Ingest a markdown file
104
- cerefox document ingest my-notes.md --project-name "personal"
105
-
106
- # Or paste content from stdin
107
- echo "# Quick Note\n\nThis is a quick note." | cerefox document ingest --paste --title "Quick Note"
108
- ```
109
-
110
- Each ingest calls the OpenAI embedding API once per batch of chunks (fast, typically under a second).
90
+ ## Managing the container
111
91
 
112
- ---
113
-
114
- ## Step 7 — Start the web UI
92
+ All host-side, via `cerefox-local`:
115
93
 
116
94
  ```bash
117
- cerefox web
95
+ cerefox-local start # start a stopped container
96
+ cerefox-local stop # stop it (your data persists in the Docker volume)
97
+ cerefox-local restart
98
+ cerefox-local logs -f # follow the logs
99
+ cerefox-local upgrade # pull the latest image + recreate (keeps data + OPENAI key)
100
+ cerefox-local uninstall # remove the container, KEEP the data volume
101
+ cerefox-local uninstall --purge # remove the container AND delete the data volume
118
102
  ```
119
103
 
120
- Open [http://localhost:8000](http://localhost:8000) in your browser.
121
-
122
- For development with auto-reload:
123
-
124
- ```bash
125
- cerefox web --reload
126
- ```
104
+ `upgrade` is the single update path: it pulls the newest image, recreates the container,
105
+ and refreshes the `cerefox-local` script itself. Because the CLI, web server, PostgREST,
106
+ and database schema all ship together in one versioned image, they never drift out of
107
+ sync.
127
108
 
128
109
  ---
129
110
 
130
- ## Step 8 — Search from the CLI
111
+ ## Where things live
131
112
 
132
- ```bash
133
- # Hybrid search (recommended)
134
- cerefox search "what did I write about project planning?"
135
-
136
- # Keyword-only search
137
- cerefox search "meeting notes" --mode fts
138
-
139
- # Semantic search
140
- cerefox search "ideas about creativity" --mode semantic
141
- ```
113
+ | Thing | Location |
114
+ |---|---|
115
+ | Container | name `cerefox-local` (override: `CEREFOX_LOCAL_CONTAINER`) |
116
+ | Your data | Docker volume `cerefox_local_pgdata` (survives `stop`/`upgrade`) |
117
+ | Host config | `~/.cerefox/local/.env` (OPENAI key + port only — **no token**) |
118
+ | Host command | `~/.cerefox/local/cerefox-local`, symlinked to `~/.local/bin/cerefox-local` |
142
119
 
143
120
  ---
144
121
 
145
- ## Running everything at once
122
+ ## Troubleshooting
146
123
 
147
- The `docker-compose.yml` also includes a `cerefox` service that runs the web UI:
124
+ **`docker not found` / can't connect** — start Docker Desktop, or `colima start`.
148
125
 
149
- ```bash
150
- docker compose up -d
151
- ```
152
-
153
- Web UI will be at [http://localhost:8000](http://localhost:8000).
126
+ **`cerefox-local: command not found`** — `~/.local/bin` isn't on your `PATH` (see Step 1).
154
127
 
155
- ---
128
+ **`container 'cerefox-local' is not running`** — `cerefox-local start` (or `status` to
129
+ check). After a reboot the container may be stopped depending on your Docker settings.
156
130
 
157
- ## Stopping services
131
+ **Ingest/search fail with no embeddings** — `OPENAI_API_KEY` wasn't set at install time.
132
+ Re-run the installer with the key, or set it and `cerefox-local upgrade`.
158
133
 
159
- ```bash
160
- docker compose down # stop, keep data
161
- docker compose down -v # stop and delete database volume
162
- ```
134
+ **Port already in use** — re-install with a free port: `PORT=8017 sh -c "$(curl -fsSL …/install-local.sh)"`.
163
135
 
164
136
  ---
165
137
 
166
- ## Updating the schema
138
+ ## Contributor notes
167
139
 
168
- When a new version of Cerefox introduces schema changes, run:
140
+ To build + test the image from a checkout (instead of pulling ghcr):
169
141
 
170
142
  ```bash
171
- bun scripts/db_migrate.ts # --status to preview, --dry-run to see SQL
143
+ docker build -f docker/local/Dockerfile -t cerefox-local:dev .
144
+ CEREFOX_LOCAL_IMAGE=cerefox-local:dev sh docker/local/install-local.sh
172
145
  ```
173
146
 
174
- This applies incremental migrations without losing data. Always back up first (see `ops-scripts.md`). End users on a hosted Supabase project run `cerefox server deploy` instead.
175
-
176
- ---
177
-
178
- ## Troubleshooting
179
-
180
- **pgvector extension not found**
181
- Make sure you're using the `pgvector/pgvector:pg16` Docker image (included in `docker-compose.yml`). Raw Postgres images do not include pgvector.
182
-
183
- **"Supabase is not configured" error**
184
- The CLI and web UI show this error if `CEREFOX_SUPABASE_URL` / `CEREFOX_SUPABASE_KEY` are empty. For local Docker setups, the app uses the direct Postgres URL (`CEREFOX_DATABASE_URL`) for schema deployment but the Supabase client for queries. Set up a local Supabase instance or use the hosted free tier (see `setup-supabase.md`).
147
+ See [`docker/local/README.md`](../../docker/local/README.md) for the image internals
148
+ (s6-overlay supervision, the `/rest/v1` proxy, the pinned PostgREST version) and
149
+ `docs/research/local-cerefox-design.md` for the design of record.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cerefox/memory",
3
- "version": "0.9.10",
3
+ "version": "0.10.0",
4
4
  "description": "Cerefox — user-owned shared memory for AI agents. The local TypeScript runtime: stdio MCP server in v0.4; CLI binary added in v0.5; in-process web server in v0.6; ingestion pipeline in v0.7.",
5
5
  "license": "Apache-2.0",
6
6
  "homepage": "https://github.com/fstamatelopoulos/cerefox",