git-memex 0.3.2__tar.gz → 0.4.0__tar.gz
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.
- {git_memex-0.3.2 → git_memex-0.4.0}/CHANGELOG.md +23 -0
- {git_memex-0.3.2/src/git_memex.egg-info → git_memex-0.4.0}/PKG-INFO +62 -33
- {git_memex-0.3.2 → git_memex-0.4.0}/README.md +59 -30
- {git_memex-0.3.2 → git_memex-0.4.0}/pyproject.toml +4 -2
- {git_memex-0.3.2 → git_memex-0.4.0/src/git_memex.egg-info}/PKG-INFO +62 -33
- {git_memex-0.3.2 → git_memex-0.4.0}/src/git_memex.egg-info/SOURCES.txt +1 -0
- git_memex-0.4.0/src/memex/__init__.py +3 -0
- {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/cli.py +55 -14
- {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/install.py +9 -5
- {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/models.py +3 -0
- {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/service.py +24 -3
- {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/store.py +71 -9
- git_memex-0.4.0/src/memex/templates/AGENTS.md +72 -0
- git_memex-0.4.0/src/memex/templates/llms.txt +81 -0
- git_memex-0.4.0/src/memex/templates/memex.mdc +17 -0
- {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/templates/skills/memex-hygiene/SKILL.md +18 -13
- {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/tools.py +14 -9
- {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/vectors.py +23 -5
- {git_memex-0.3.2 → git_memex-0.4.0}/tests/test_cli.py +47 -1
- {git_memex-0.3.2 → git_memex-0.4.0}/tests/test_install.py +41 -13
- {git_memex-0.3.2 → git_memex-0.4.0}/tests/test_store.py +40 -0
- {git_memex-0.3.2 → git_memex-0.4.0}/tests/test_tools.py +38 -1
- {git_memex-0.3.2 → git_memex-0.4.0}/tests/test_vectors.py +36 -0
- git_memex-0.3.2/src/memex/__init__.py +0 -3
- git_memex-0.3.2/src/memex/templates/AGENTS.md +0 -65
- git_memex-0.3.2/src/memex/templates/memex.mdc +0 -15
- {git_memex-0.3.2 → git_memex-0.4.0}/LICENSE +0 -0
- {git_memex-0.3.2 → git_memex-0.4.0}/MANIFEST.in +0 -0
- {git_memex-0.3.2 → git_memex-0.4.0}/examples/claude-mcp.json +0 -0
- {git_memex-0.3.2 → git_memex-0.4.0}/examples/codex-config.toml +0 -0
- {git_memex-0.3.2 → git_memex-0.4.0}/examples/cursor-mcp.json +0 -0
- {git_memex-0.3.2 → git_memex-0.4.0}/setup.cfg +0 -0
- {git_memex-0.3.2 → git_memex-0.4.0}/src/git_memex.egg-info/dependency_links.txt +0 -0
- {git_memex-0.3.2 → git_memex-0.4.0}/src/git_memex.egg-info/entry_points.txt +0 -0
- {git_memex-0.3.2 → git_memex-0.4.0}/src/git_memex.egg-info/requires.txt +0 -0
- {git_memex-0.3.2 → git_memex-0.4.0}/src/git_memex.egg-info/top_level.txt +0 -0
- {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/__main__.py +0 -0
- {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/config.py +0 -0
- {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/embedder.py +0 -0
- {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/gitroot.py +0 -0
- {git_memex-0.3.2 → git_memex-0.4.0}/src/memex/server.py +0 -0
- {git_memex-0.3.2 → git_memex-0.4.0}/tests/test_embedder.py +0 -0
- {git_memex-0.3.2 → git_memex-0.4.0}/tests/test_gitroot.py +0 -0
- {git_memex-0.3.2 → git_memex-0.4.0}/tests/test_merge_reindex.py +0 -0
|
@@ -2,6 +2,29 @@
|
|
|
2
2
|
|
|
3
3
|
## Unreleased
|
|
4
4
|
|
|
5
|
+
## 0.4.0 — 2026-11-10
|
|
6
|
+
|
|
7
|
+
- **CLI-first agent integration.** Agent prompts (`AGENTS.md` block, Cursor
|
|
8
|
+
rule, `memex-hygiene` skill) now tell agents to run the `memex` CLI
|
|
9
|
+
(`memex recall "…"`, `memex remember "…" --tags …`) instead of MCP tools, so
|
|
10
|
+
Memex works in any harness that can run shell commands.
|
|
11
|
+
- New `memex llms` (alias `memex llms.txt`): prints an `llms.txt`-style agent
|
|
12
|
+
guide — workflow, every command and flag, JSON shapes, env vars.
|
|
13
|
+
- `memex remember -` reads the fact from stdin (avoids shell quoting).
|
|
14
|
+
- New install target `agents`: writes only the `AGENTS.md` block + layout, for
|
|
15
|
+
harnesses without dedicated wiring. `all` now includes it.
|
|
16
|
+
- **Breaking:** `memex install` no longer writes MCP config by default; pass
|
|
17
|
+
`--mcp` to write `.cursor/mcp.json` / `.mcp.json` / `.codex/config.toml`.
|
|
18
|
+
`--no-mcp` is still accepted (now a no-op). Existing MCP config is left as is.
|
|
19
|
+
- Fixed a date-dependent recency ranking test that failed once its fixed
|
|
20
|
+
"fresh" timestamp aged past the 30-day half-life.
|
|
21
|
+
|
|
22
|
+
## 0.3.3 — 2026-09-06
|
|
23
|
+
|
|
24
|
+
- Optional note **`paths`**: durable related scope (repo-relative files/folders)
|
|
25
|
+
on frontmatter and in `memory.db`. Pass via `remember` / `--paths`; returned on
|
|
26
|
+
`recall` and `list`. Not a session changelog; no ranking boost yet.
|
|
27
|
+
|
|
5
28
|
## 0.3.2 — 2026-08-21
|
|
6
29
|
|
|
7
30
|
- `recall` adds opt-in recency boosting, `tags_all` AND filtering, and
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: git-memex
|
|
3
|
-
Version: 0.
|
|
4
|
-
Summary: Memex: repo-local vector memory — CLI
|
|
3
|
+
Version: 0.4.0
|
|
4
|
+
Summary: Memex: repo-local vector memory for AI agents — CLI-first remember/recall inside the git repository (optional MCP)
|
|
5
5
|
Author: Daniel
|
|
6
6
|
License-Expression: MIT
|
|
7
7
|
Project-URL: Homepage, https://github.com/daniel/memex
|
|
8
8
|
Project-URL: Repository, https://github.com/daniel/memex
|
|
9
|
-
Keywords: mcp,agent-memory,vector-search,sqlite-vec,git
|
|
9
|
+
Keywords: cli,llms-txt,mcp,agent-memory,vector-search,sqlite-vec,git
|
|
10
10
|
Classifier: Development Status :: 4 - Beta
|
|
11
11
|
Classifier: Intended Audience :: Developers
|
|
12
12
|
Classifier: Programming Language :: Python :: 3
|
|
@@ -31,7 +31,10 @@ Dynamic: license-file
|
|
|
31
31
|
|
|
32
32
|
Repo-local vector memory for AI agents. Memories live **inside the git repository**
|
|
33
33
|
as mergeable markdown notes plus a rebuildable sqlite-vec index. Use the `memex`
|
|
34
|
-
CLI
|
|
34
|
+
CLI to `remember` and `recall` by semantic relevance. The CLI is the primary
|
|
35
|
+
interface, so it works in any LLM harness that can run shell commands; agents
|
|
36
|
+
get a full usage guide from `memex llms` (an `llms.txt`). A stdio MCP server
|
|
37
|
+
(`memex serve`) is available as an opt-in extra.
|
|
35
38
|
|
|
36
39
|
Published on PyPI as [`git-memex`](https://pypi.org/project/git-memex/) (`memex` was already taken).
|
|
37
40
|
|
|
@@ -74,10 +77,11 @@ uv run pytest
|
|
|
74
77
|
|
|
75
78
|
On Linux/WSL, use `python3` if `python` is not found.
|
|
76
79
|
|
|
77
|
-
##
|
|
80
|
+
## Optional MCP config
|
|
78
81
|
|
|
79
|
-
|
|
80
|
-
|
|
82
|
+
Agents use the CLI by default. To also register the MCP server, pass `--mcp`:
|
|
83
|
+
**`memex install cursor --mcp`** writes `.cursor/mcp.json` with a portable home
|
|
84
|
+
path (after `uv tool install` / `pipx`):
|
|
81
85
|
|
|
82
86
|
```json
|
|
83
87
|
{
|
|
@@ -103,15 +107,23 @@ the server walks parents from the process cwd looking for `.git`.
|
|
|
103
107
|
|
|
104
108
|
## Claude Desktop / Claude Code
|
|
105
109
|
|
|
106
|
-
For Claude Code, prefer **`memex install claude`** (writes
|
|
107
|
-
`
|
|
108
|
-
`examples/claude-mcp.json`.
|
|
110
|
+
For Claude Code, prefer **`memex install claude`** (writes `CLAUDE.md`; add
|
|
111
|
+
`--mcp` for project `.mcp.json`). Default MCP command is bare `memex` (on PATH).
|
|
112
|
+
See `examples/claude-mcp.json`.
|
|
109
113
|
|
|
110
114
|
## Codex
|
|
111
115
|
|
|
112
|
-
Prefer **`memex install codex
|
|
116
|
+
Prefer **`memex install codex`** (writes `AGENTS.md`; add `--mcp` for the
|
|
117
|
+
`.codex/config.toml` block). Default MCP command is bare `memex`; Codex still
|
|
113
118
|
gets an absolute `MEMEX_ROOT` for the repo. See `examples/codex-config.toml`.
|
|
114
119
|
|
|
120
|
+
## Any other harness
|
|
121
|
+
|
|
122
|
+
**`memex install agents`** writes only the CLI-first Memex block to `AGENTS.md`
|
|
123
|
+
(plus `.memex/` layout and `.gitattributes`). Any agent that reads `AGENTS.md`
|
|
124
|
+
and can run shell commands can then use Memex; point it at `memex llms` for
|
|
125
|
+
the full reference.
|
|
126
|
+
|
|
115
127
|
## On-disk layout
|
|
116
128
|
|
|
117
129
|
```text
|
|
@@ -130,16 +142,21 @@ pull that changes notes, the next `recall` auto-reindexes if the DB is stale.
|
|
|
130
142
|
## CLI
|
|
131
143
|
|
|
132
144
|
After install, the `memex` console script is a CLI. Running `memex` with no
|
|
133
|
-
arguments prints help.
|
|
145
|
+
arguments prints help. `memex llms` prints the agent guide (`llms.txt`: workflow,
|
|
146
|
+
every command and flag, JSON shapes). Start the optional MCP server with
|
|
147
|
+
`memex serve`.
|
|
134
148
|
|
|
135
149
|
```bash
|
|
136
150
|
memex # show help
|
|
137
151
|
memex help
|
|
138
152
|
memex help install
|
|
139
|
-
memex
|
|
140
|
-
memex install
|
|
141
|
-
memex install
|
|
153
|
+
memex llms # agent/LLM usage guide (llms.txt)
|
|
154
|
+
memex install agents # AGENTS.md only (any harness)
|
|
155
|
+
memex install cursor # AGENTS.md + Cursor rule + .cursor/skills
|
|
156
|
+
memex install claude # AGENTS.md + CLAUDE.md
|
|
157
|
+
memex install codex # AGENTS.md
|
|
142
158
|
memex install all
|
|
159
|
+
memex install all --mcp # also write MCP server configs
|
|
143
160
|
memex status
|
|
144
161
|
memex list
|
|
145
162
|
memex list --tags decision --limit 20
|
|
@@ -147,12 +164,14 @@ memex list --tags-all auth,decision --offset 20 --limit 20
|
|
|
147
164
|
memex reindex # rebuild memory.db from .memex/notes
|
|
148
165
|
memex reindex --force # rebuild even when fingerprints match
|
|
149
166
|
memex remember "We use JWT in httpOnly cookies" --tags auth,decision
|
|
167
|
+
memex remember "Auth lives in the cookie middleware" --tags auth,bugfix --paths src/auth/
|
|
150
168
|
memex remember "Strip locale from JWT" --replaces <uuid>
|
|
169
|
+
echo "Fact with \"quotes\"" | memex remember - --tags convention # read from stdin
|
|
151
170
|
memex recall "how is auth handled?" -k 5
|
|
152
171
|
memex recall "how is auth handled?" --tags-all auth,security --recency
|
|
153
172
|
memex recall "how is auth handled?" --rank blended
|
|
154
173
|
memex forget <uuid>
|
|
155
|
-
memex serve # stdio MCP server
|
|
174
|
+
memex serve # optional stdio MCP server
|
|
156
175
|
```
|
|
157
176
|
|
|
158
177
|
Add `--json` to any command for machine-readable output. From a checkout:
|
|
@@ -163,13 +182,15 @@ make reindex
|
|
|
163
182
|
make reindex FORCE=1
|
|
164
183
|
```
|
|
165
184
|
|
|
166
|
-
## MCP tools
|
|
185
|
+
## MCP tools (optional)
|
|
186
|
+
|
|
187
|
+
`memex serve` exposes the same operations as MCP tools:
|
|
167
188
|
|
|
168
189
|
| Tool | Purpose |
|
|
169
190
|
|------|---------|
|
|
170
|
-
| `remember` | Store a memory; skips/updates near-duplicates & elaborations; `replaces` updates by id |
|
|
171
|
-
| `recall` | Semantic KNN search; returns untrusted evidence with timestamps |
|
|
172
|
-
| `list` | Catalog notes (id, first line, tags, dates) without embeddings |
|
|
191
|
+
| `remember` | Store a memory; skips/updates near-duplicates & elaborations; `replaces` updates by id; optional `paths` for related scope |
|
|
192
|
+
| `recall` | Semantic KNN search; returns untrusted evidence with timestamps and optional `paths` |
|
|
193
|
+
| `list` | Catalog notes (id, first line, tags, paths, dates) without embeddings |
|
|
173
194
|
| `reindex` | Rebuild `memory.db` from notes |
|
|
174
195
|
| `forget` | Delete a memory by id |
|
|
175
196
|
| `status` | Repo root, counts, tag histogram, model, staleness |
|
|
@@ -180,6 +201,8 @@ tag; `--tags-all` requires every listed tag. `--recency` applies a bounded
|
|
|
180
201
|
freshness boost with a 30-day half-life. `--rank blended` opts into combined
|
|
181
202
|
semantic, freshness, tag-overlap, and type-tag ranking; cosine remains the
|
|
182
203
|
default and the returned `score` remains raw cosine similarity.
|
|
204
|
+
Optional `paths` on `remember` (comma-separated repo-relative files/folders) is
|
|
205
|
+
durable related scope for bugfixes and module conventions—not a session diff.
|
|
183
206
|
When `remember` inserts a new note that is close to an existing one, the response
|
|
184
207
|
includes `conflicts` and may include advisory `suggested_tags`. Recall hits may
|
|
185
208
|
include `conflict: true` when multiple near-neighbor notes could represent
|
|
@@ -200,11 +223,13 @@ verify important notes against the repository.
|
|
|
200
223
|
In any git repository where agents should use Memex, install for your platform(s):
|
|
201
224
|
|
|
202
225
|
```bash
|
|
226
|
+
memex install agents # AGENTS.md only — any harness
|
|
203
227
|
memex install cursor
|
|
204
228
|
memex install claude
|
|
205
229
|
memex install codex
|
|
206
|
-
memex install all # cursor + claude + codex
|
|
230
|
+
memex install all # agents + cursor + claude + codex
|
|
207
231
|
memex install cursor claude # multiple targets
|
|
232
|
+
memex install all --mcp # also write MCP server configs
|
|
208
233
|
```
|
|
209
234
|
|
|
210
235
|
Every target is idempotent and always:
|
|
@@ -218,27 +243,31 @@ Platform extras:
|
|
|
218
243
|
|
|
219
244
|
| Target | Also writes |
|
|
220
245
|
|--------|-------------|
|
|
221
|
-
| `
|
|
222
|
-
| `
|
|
223
|
-
| `
|
|
246
|
+
| `agents` | nothing else |
|
|
247
|
+
| `cursor` | short always-on `.cursor/rules/memex.mdc` (points at the `AGENTS.md` Memex block), `.cursor/skills/` from `templates/skills/`; with `--mcp`: `.cursor/mcp.json` (`${userHome}/…`, `MEMEX_ROOT=${workspaceFolder}`) |
|
|
248
|
+
| `claude` | `CLAUDE.md`; with `--mcp`: `.mcp.json` (`command: memex`, `MEMEX_ROOT=${CLAUDE_PROJECT_DIR:-.}`) |
|
|
249
|
+
| `codex` | with `--mcp`: `.codex/config.toml` MCP block (`command: memex`, absolute `MEMEX_ROOT`) |
|
|
224
250
|
|
|
225
251
|
Re-run after upgrading `git-memex` to refresh prompts from packaged templates.
|
|
226
|
-
Flags: `--no-agents`, `--no-instructions`, `--no-rules`,
|
|
227
|
-
`--no-skills`, `--no-gitattributes`, `--command /path/to/memex
|
|
252
|
+
Flags: `--mcp`, `--no-agents`, `--no-instructions`, `--no-rules`,
|
|
253
|
+
`--no-skills`, `--no-gitattributes`, `--command /path/to/memex` (MCP binary).
|
|
254
|
+
Re-running without `--mcp` never removes MCP config written earlier.
|
|
228
255
|
|
|
229
256
|
Templates live in the package (`src/memex/templates/`). `AGENTS.md` is the
|
|
230
|
-
canonical agent prompt
|
|
257
|
+
canonical agent prompt and tells agents to use the `memex` CLI (and
|
|
258
|
+
`memex llms` for the full reference); `src/memex/templates/llms.txt` is that
|
|
259
|
+
reference. The Cursor `.mdc` is a short always-on pointer at that
|
|
231
260
|
block (Claude gets the same block in `CLAUDE.md`). Cursor skills live
|
|
232
261
|
under `templates/skills/` and are copied into the target repo's
|
|
233
262
|
`.cursor/skills/` (today: `memex-hygiene` to audit stale/stacked notes;
|
|
234
263
|
user-invoked only). The agent files tell agents to
|
|
235
|
-
**`recall` (MUST) before non-trivial / unfamiliar work, when debugging, and
|
|
264
|
+
**`memex recall` (MUST) before non-trivial / unfamiliar work, when debugging, and
|
|
236
265
|
when choices depend on project or business rules**, with sample queries and
|
|
237
|
-
skip criteria for trivial edits, and to **`remember` durable decisions,
|
|
266
|
+
skip criteria for trivial edits, and to **`memex remember` durable decisions,
|
|
238
267
|
project/business rules, and solved problems** (symptoms → cause → fix).
|
|
239
|
-
If a new fact supersedes an old note, agents should pass
|
|
240
|
-
`forget` the old id) rather than stacking a second memory. `list`
|
|
241
|
-
what is stored; do not dummy
|
|
268
|
+
If a new fact supersedes an old note, agents should pass `--replaces <id>` (or
|
|
269
|
+
`memex forget` the old id) rather than stacking a second memory. `memex list`
|
|
270
|
+
catalogs what is stored; do not dummy-recall with a large `-k`.
|
|
242
271
|
|
|
243
272
|
## Environment
|
|
244
273
|
|
|
@@ -255,7 +284,7 @@ what is stored; do not dummy-`recall` with a large `k`.
|
|
|
255
284
|
|---------|-----|
|
|
256
285
|
| `command not found: python` | Use `python3` (common on Linux/WSL) |
|
|
257
286
|
| `command not found: memex` | Activate the venv, use `.venv/bin/memex`, or install globally (`uv tool install git-memex` / `pipx install git-memex`) |
|
|
258
|
-
| `spawn … memex ENOENT` | Wrong or missing binary — default is `${userHome}/.local/bin/memex`; override with `--command` or install via `uv tool install git-memex` |
|
|
287
|
+
| `spawn … memex ENOENT` (MCP) | Wrong or missing binary — default is `${userHome}/.local/bin/memex`; override with `--command` or install via `uv tool install git-memex` |
|
|
259
288
|
| `not a git repository` | Open a git checkout, or set `MEMEX_ROOT` to the repo root |
|
|
260
289
|
| `sqlite-vec is not installed` / extension load failed | Use a CPython build that supports loadable extensions (not some OS-default Pythons); `pip install sqlite-vec` |
|
|
261
290
|
| `MODEL.json pins … but embedder is …` | Same model for the whole team, or `memex reindex --force` after intentional model change |
|
|
@@ -2,7 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
Repo-local vector memory for AI agents. Memories live **inside the git repository**
|
|
4
4
|
as mergeable markdown notes plus a rebuildable sqlite-vec index. Use the `memex`
|
|
5
|
-
CLI
|
|
5
|
+
CLI to `remember` and `recall` by semantic relevance. The CLI is the primary
|
|
6
|
+
interface, so it works in any LLM harness that can run shell commands; agents
|
|
7
|
+
get a full usage guide from `memex llms` (an `llms.txt`). A stdio MCP server
|
|
8
|
+
(`memex serve`) is available as an opt-in extra.
|
|
6
9
|
|
|
7
10
|
Published on PyPI as [`git-memex`](https://pypi.org/project/git-memex/) (`memex` was already taken).
|
|
8
11
|
|
|
@@ -45,10 +48,11 @@ uv run pytest
|
|
|
45
48
|
|
|
46
49
|
On Linux/WSL, use `python3` if `python` is not found.
|
|
47
50
|
|
|
48
|
-
##
|
|
51
|
+
## Optional MCP config
|
|
49
52
|
|
|
50
|
-
|
|
51
|
-
|
|
53
|
+
Agents use the CLI by default. To also register the MCP server, pass `--mcp`:
|
|
54
|
+
**`memex install cursor --mcp`** writes `.cursor/mcp.json` with a portable home
|
|
55
|
+
path (after `uv tool install` / `pipx`):
|
|
52
56
|
|
|
53
57
|
```json
|
|
54
58
|
{
|
|
@@ -74,15 +78,23 @@ the server walks parents from the process cwd looking for `.git`.
|
|
|
74
78
|
|
|
75
79
|
## Claude Desktop / Claude Code
|
|
76
80
|
|
|
77
|
-
For Claude Code, prefer **`memex install claude`** (writes
|
|
78
|
-
`
|
|
79
|
-
`examples/claude-mcp.json`.
|
|
81
|
+
For Claude Code, prefer **`memex install claude`** (writes `CLAUDE.md`; add
|
|
82
|
+
`--mcp` for project `.mcp.json`). Default MCP command is bare `memex` (on PATH).
|
|
83
|
+
See `examples/claude-mcp.json`.
|
|
80
84
|
|
|
81
85
|
## Codex
|
|
82
86
|
|
|
83
|
-
Prefer **`memex install codex
|
|
87
|
+
Prefer **`memex install codex`** (writes `AGENTS.md`; add `--mcp` for the
|
|
88
|
+
`.codex/config.toml` block). Default MCP command is bare `memex`; Codex still
|
|
84
89
|
gets an absolute `MEMEX_ROOT` for the repo. See `examples/codex-config.toml`.
|
|
85
90
|
|
|
91
|
+
## Any other harness
|
|
92
|
+
|
|
93
|
+
**`memex install agents`** writes only the CLI-first Memex block to `AGENTS.md`
|
|
94
|
+
(plus `.memex/` layout and `.gitattributes`). Any agent that reads `AGENTS.md`
|
|
95
|
+
and can run shell commands can then use Memex; point it at `memex llms` for
|
|
96
|
+
the full reference.
|
|
97
|
+
|
|
86
98
|
## On-disk layout
|
|
87
99
|
|
|
88
100
|
```text
|
|
@@ -101,16 +113,21 @@ pull that changes notes, the next `recall` auto-reindexes if the DB is stale.
|
|
|
101
113
|
## CLI
|
|
102
114
|
|
|
103
115
|
After install, the `memex` console script is a CLI. Running `memex` with no
|
|
104
|
-
arguments prints help.
|
|
116
|
+
arguments prints help. `memex llms` prints the agent guide (`llms.txt`: workflow,
|
|
117
|
+
every command and flag, JSON shapes). Start the optional MCP server with
|
|
118
|
+
`memex serve`.
|
|
105
119
|
|
|
106
120
|
```bash
|
|
107
121
|
memex # show help
|
|
108
122
|
memex help
|
|
109
123
|
memex help install
|
|
110
|
-
memex
|
|
111
|
-
memex install
|
|
112
|
-
memex install
|
|
124
|
+
memex llms # agent/LLM usage guide (llms.txt)
|
|
125
|
+
memex install agents # AGENTS.md only (any harness)
|
|
126
|
+
memex install cursor # AGENTS.md + Cursor rule + .cursor/skills
|
|
127
|
+
memex install claude # AGENTS.md + CLAUDE.md
|
|
128
|
+
memex install codex # AGENTS.md
|
|
113
129
|
memex install all
|
|
130
|
+
memex install all --mcp # also write MCP server configs
|
|
114
131
|
memex status
|
|
115
132
|
memex list
|
|
116
133
|
memex list --tags decision --limit 20
|
|
@@ -118,12 +135,14 @@ memex list --tags-all auth,decision --offset 20 --limit 20
|
|
|
118
135
|
memex reindex # rebuild memory.db from .memex/notes
|
|
119
136
|
memex reindex --force # rebuild even when fingerprints match
|
|
120
137
|
memex remember "We use JWT in httpOnly cookies" --tags auth,decision
|
|
138
|
+
memex remember "Auth lives in the cookie middleware" --tags auth,bugfix --paths src/auth/
|
|
121
139
|
memex remember "Strip locale from JWT" --replaces <uuid>
|
|
140
|
+
echo "Fact with \"quotes\"" | memex remember - --tags convention # read from stdin
|
|
122
141
|
memex recall "how is auth handled?" -k 5
|
|
123
142
|
memex recall "how is auth handled?" --tags-all auth,security --recency
|
|
124
143
|
memex recall "how is auth handled?" --rank blended
|
|
125
144
|
memex forget <uuid>
|
|
126
|
-
memex serve # stdio MCP server
|
|
145
|
+
memex serve # optional stdio MCP server
|
|
127
146
|
```
|
|
128
147
|
|
|
129
148
|
Add `--json` to any command for machine-readable output. From a checkout:
|
|
@@ -134,13 +153,15 @@ make reindex
|
|
|
134
153
|
make reindex FORCE=1
|
|
135
154
|
```
|
|
136
155
|
|
|
137
|
-
## MCP tools
|
|
156
|
+
## MCP tools (optional)
|
|
157
|
+
|
|
158
|
+
`memex serve` exposes the same operations as MCP tools:
|
|
138
159
|
|
|
139
160
|
| Tool | Purpose |
|
|
140
161
|
|------|---------|
|
|
141
|
-
| `remember` | Store a memory; skips/updates near-duplicates & elaborations; `replaces` updates by id |
|
|
142
|
-
| `recall` | Semantic KNN search; returns untrusted evidence with timestamps |
|
|
143
|
-
| `list` | Catalog notes (id, first line, tags, dates) without embeddings |
|
|
162
|
+
| `remember` | Store a memory; skips/updates near-duplicates & elaborations; `replaces` updates by id; optional `paths` for related scope |
|
|
163
|
+
| `recall` | Semantic KNN search; returns untrusted evidence with timestamps and optional `paths` |
|
|
164
|
+
| `list` | Catalog notes (id, first line, tags, paths, dates) without embeddings |
|
|
144
165
|
| `reindex` | Rebuild `memory.db` from notes |
|
|
145
166
|
| `forget` | Delete a memory by id |
|
|
146
167
|
| `status` | Repo root, counts, tag histogram, model, staleness |
|
|
@@ -151,6 +172,8 @@ tag; `--tags-all` requires every listed tag. `--recency` applies a bounded
|
|
|
151
172
|
freshness boost with a 30-day half-life. `--rank blended` opts into combined
|
|
152
173
|
semantic, freshness, tag-overlap, and type-tag ranking; cosine remains the
|
|
153
174
|
default and the returned `score` remains raw cosine similarity.
|
|
175
|
+
Optional `paths` on `remember` (comma-separated repo-relative files/folders) is
|
|
176
|
+
durable related scope for bugfixes and module conventions—not a session diff.
|
|
154
177
|
When `remember` inserts a new note that is close to an existing one, the response
|
|
155
178
|
includes `conflicts` and may include advisory `suggested_tags`. Recall hits may
|
|
156
179
|
include `conflict: true` when multiple near-neighbor notes could represent
|
|
@@ -171,11 +194,13 @@ verify important notes against the repository.
|
|
|
171
194
|
In any git repository where agents should use Memex, install for your platform(s):
|
|
172
195
|
|
|
173
196
|
```bash
|
|
197
|
+
memex install agents # AGENTS.md only — any harness
|
|
174
198
|
memex install cursor
|
|
175
199
|
memex install claude
|
|
176
200
|
memex install codex
|
|
177
|
-
memex install all # cursor + claude + codex
|
|
201
|
+
memex install all # agents + cursor + claude + codex
|
|
178
202
|
memex install cursor claude # multiple targets
|
|
203
|
+
memex install all --mcp # also write MCP server configs
|
|
179
204
|
```
|
|
180
205
|
|
|
181
206
|
Every target is idempotent and always:
|
|
@@ -189,27 +214,31 @@ Platform extras:
|
|
|
189
214
|
|
|
190
215
|
| Target | Also writes |
|
|
191
216
|
|--------|-------------|
|
|
192
|
-
| `
|
|
193
|
-
| `
|
|
194
|
-
| `
|
|
217
|
+
| `agents` | nothing else |
|
|
218
|
+
| `cursor` | short always-on `.cursor/rules/memex.mdc` (points at the `AGENTS.md` Memex block), `.cursor/skills/` from `templates/skills/`; with `--mcp`: `.cursor/mcp.json` (`${userHome}/…`, `MEMEX_ROOT=${workspaceFolder}`) |
|
|
219
|
+
| `claude` | `CLAUDE.md`; with `--mcp`: `.mcp.json` (`command: memex`, `MEMEX_ROOT=${CLAUDE_PROJECT_DIR:-.}`) |
|
|
220
|
+
| `codex` | with `--mcp`: `.codex/config.toml` MCP block (`command: memex`, absolute `MEMEX_ROOT`) |
|
|
195
221
|
|
|
196
222
|
Re-run after upgrading `git-memex` to refresh prompts from packaged templates.
|
|
197
|
-
Flags: `--no-agents`, `--no-instructions`, `--no-rules`,
|
|
198
|
-
`--no-skills`, `--no-gitattributes`, `--command /path/to/memex
|
|
223
|
+
Flags: `--mcp`, `--no-agents`, `--no-instructions`, `--no-rules`,
|
|
224
|
+
`--no-skills`, `--no-gitattributes`, `--command /path/to/memex` (MCP binary).
|
|
225
|
+
Re-running without `--mcp` never removes MCP config written earlier.
|
|
199
226
|
|
|
200
227
|
Templates live in the package (`src/memex/templates/`). `AGENTS.md` is the
|
|
201
|
-
canonical agent prompt
|
|
228
|
+
canonical agent prompt and tells agents to use the `memex` CLI (and
|
|
229
|
+
`memex llms` for the full reference); `src/memex/templates/llms.txt` is that
|
|
230
|
+
reference. The Cursor `.mdc` is a short always-on pointer at that
|
|
202
231
|
block (Claude gets the same block in `CLAUDE.md`). Cursor skills live
|
|
203
232
|
under `templates/skills/` and are copied into the target repo's
|
|
204
233
|
`.cursor/skills/` (today: `memex-hygiene` to audit stale/stacked notes;
|
|
205
234
|
user-invoked only). The agent files tell agents to
|
|
206
|
-
**`recall` (MUST) before non-trivial / unfamiliar work, when debugging, and
|
|
235
|
+
**`memex recall` (MUST) before non-trivial / unfamiliar work, when debugging, and
|
|
207
236
|
when choices depend on project or business rules**, with sample queries and
|
|
208
|
-
skip criteria for trivial edits, and to **`remember` durable decisions,
|
|
237
|
+
skip criteria for trivial edits, and to **`memex remember` durable decisions,
|
|
209
238
|
project/business rules, and solved problems** (symptoms → cause → fix).
|
|
210
|
-
If a new fact supersedes an old note, agents should pass
|
|
211
|
-
`forget` the old id) rather than stacking a second memory. `list`
|
|
212
|
-
what is stored; do not dummy
|
|
239
|
+
If a new fact supersedes an old note, agents should pass `--replaces <id>` (or
|
|
240
|
+
`memex forget` the old id) rather than stacking a second memory. `memex list`
|
|
241
|
+
catalogs what is stored; do not dummy-recall with a large `-k`.
|
|
213
242
|
|
|
214
243
|
## Environment
|
|
215
244
|
|
|
@@ -226,7 +255,7 @@ what is stored; do not dummy-`recall` with a large `k`.
|
|
|
226
255
|
|---------|-----|
|
|
227
256
|
| `command not found: python` | Use `python3` (common on Linux/WSL) |
|
|
228
257
|
| `command not found: memex` | Activate the venv, use `.venv/bin/memex`, or install globally (`uv tool install git-memex` / `pipx install git-memex`) |
|
|
229
|
-
| `spawn … memex ENOENT` | Wrong or missing binary — default is `${userHome}/.local/bin/memex`; override with `--command` or install via `uv tool install git-memex` |
|
|
258
|
+
| `spawn … memex ENOENT` (MCP) | Wrong or missing binary — default is `${userHome}/.local/bin/memex`; override with `--command` or install via `uv tool install git-memex` |
|
|
230
259
|
| `not a git repository` | Open a git checkout, or set `MEMEX_ROOT` to the repo root |
|
|
231
260
|
| `sqlite-vec is not installed` / extension load failed | Use a CPython build that supports loadable extensions (not some OS-default Pythons); `pip install sqlite-vec` |
|
|
232
261
|
| `MODEL.json pins … but embedder is …` | Same model for the whole team, or `memex reindex --force` after intentional model change |
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "git-memex"
|
|
3
|
-
version = "0.
|
|
4
|
-
description = "Memex: repo-local vector memory — CLI
|
|
3
|
+
version = "0.4.0"
|
|
4
|
+
description = "Memex: repo-local vector memory for AI agents — CLI-first remember/recall inside the git repository (optional MCP)"
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
license = "MIT"
|
|
7
7
|
requires-python = ">=3.11"
|
|
@@ -9,6 +9,8 @@ authors = [
|
|
|
9
9
|
{ name = "Daniel" },
|
|
10
10
|
]
|
|
11
11
|
keywords = [
|
|
12
|
+
"cli",
|
|
13
|
+
"llms-txt",
|
|
12
14
|
"mcp",
|
|
13
15
|
"agent-memory",
|
|
14
16
|
"vector-search",
|