Skip to content

Commit f430feb

Browse files
jack-arturoclaude
andauthored
docs: fix drift in Project Structure (#224)
Source-note SHA (automem@1b812cf, mcp-automem@b81c63a) had drifted far behind current main on both repos, and several structural claims about mcp-automem no longer match reality: the plugins/ package layout, the AutoMemClient method table, a CLI file that doesn't exist, and the version-sync file paths release-please actually manages. 🤖 Generated by the AutoMem docs-accuracy audit routine. Co-authored-by: Claude <noreply@anthropic.com>
1 parent 1417959 commit f430feb

1 file changed

Lines changed: 22 additions & 19 deletions

File tree

src/content/docs/docs/development/structure.md

Lines changed: 22 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -159,7 +159,7 @@ Self-contained consolidation engine with no Flask dependencies. Designed for bot
159159
| `GraphLike` (Protocol) | Database abstraction | `query()` method only |
160160
| `VectorStoreProtocol` (Protocol) | Vector store abstraction | `delete()` method only |
161161

162-
**Caching optimization**: Relationship count queries use `@lru_cache` with hourly invalidation ([consolidation.py:152-176](https://github.com/verygoodplugins/automem/blob/1b812cf883cbc95632d5f9f1ed180d1865c0638a/consolidation.py#L152-L176)).
162+
**Caching optimization**: Relationship count queries use `@lru_cache` with hourly invalidation ([consolidation.py:201-217](https://github.com/verygoodplugins/automem/blob/3ae04bf6f4545f38744e4c3f280b763db881a6fb/consolidation.py#L201-L217)).
163163

164164
:::tip[Flask independence]
165165
`consolidation.py` is deliberately Flask-independent. It can be imported and used in CLI scripts or schedulers without Flask overhead. The `GraphLike` and `VectorStoreProtocol` protocols enable testing with in-memory mocks.
@@ -244,10 +244,10 @@ tests/
244244

245245
Tests use pytest markers to separate execution tiers: `unit` (no external services, runs with `make test`), `integration` (requires Docker stack, runs with `make test-integration`), and `live` (runs against a deployed Railway instance).
246246

247-
**Mock objects** (defined in [`tests/test_consolidation_engine.py`](https://github.com/verygoodplugins/automem/blob/1b812cf883cbc95632d5f9f1ed180d1865c0638a/tests/test_consolidation_engine.py) and `tests/support/`):
247+
**Mock objects** (defined in [`tests/test_consolidation_engine.py`](https://github.com/verygoodplugins/automem/blob/3ae04bf6f4545f38744e4c3f280b763db881a6fb/tests/test_consolidation_engine.py) and `tests/support/`):
248248

249-
- `FakeGraph`: Implements `GraphLike` protocol with in-memory state — imported from [`tests/support/fake_graph.py`](https://github.com/verygoodplugins/automem/blob/1b812cf883cbc95632d5f9f1ed180d1865c0638a/tests/support/fake_graph.py)
250-
- `FakeVectorStore`: Implements `VectorStoreProtocol` for deletion tracking — defined in [`tests/test_consolidation_engine.py` ~L11](https://github.com/verygoodplugins/automem/blob/1b812cf883cbc95632d5f9f1ed180d1865c0638a/tests/test_consolidation_engine.py#L11)
249+
- `FakeGraph`: Implements `GraphLike` protocol with in-memory state — imported from [`tests/support/fake_graph.py`](https://github.com/verygoodplugins/automem/blob/3ae04bf6f4545f38744e4c3f280b763db881a6fb/tests/support/fake_graph.py)
250+
- `FakeVectorStore`: Implements `VectorStoreProtocol` for deletion tracking — defined in [`tests/test_consolidation_engine.py:19-24`](https://github.com/verygoodplugins/automem/blob/3ae04bf6f4545f38744e4c3f280b763db881a6fb/tests/test_consolidation_engine.py#L19-L24)
251251

252252
**Test philosophy**: Consolidation tests use deterministic mocks and frozen time to ensure reproducible relevance score calculations.
253253

@@ -302,7 +302,6 @@ graph TB
302302
CLI --> SETUP["setup.ts"]
303303
CLI --> CLAUDECODE["claude-code.ts"]
304304
CLI --> QUEUE["queue.ts"]
305-
CLI --> CONFIG["config.ts"]
306305
CLI --> CURSOR["cursor.ts"]
307306
CLI --> CODEX["codex.ts"]
308307
CLI --> OPENCLAW["openclaw.ts"]
@@ -313,8 +312,13 @@ graph TB
313312
TEMPLATES --> TOCLAW["openclaw/\nSKILL.md"]
314313
TEMPLATES --> TWARP["warp/\nwarp-rules.md"]
315314
316-
PLUGINS --> PCCLI[".claude-plugin/\nmarketplace files"]
317-
PLUGINS --> PSERVER["server/\nserver.json metadata"]
315+
PLUGINS --> PAUTOMEM["automem/"]
316+
PAUTOMEM --> PCCLI[".claude-plugin/\nplugin.json"]
317+
PAUTOMEM --> PCOMMANDS["commands/"]
318+
PAUTOMEM --> PHOOKS["hooks/"]
319+
PAUTOMEM --> PSCRIPTS["scripts/"]
320+
PAUTOMEM --> PSKILLS["skills/\nmemory-management/"]
321+
ROOT --> ROOTPLUGIN[".claude-plugin/\nmarketplace.json"]
318322
319323
GITHUB --> WORKFLOWS["workflows/\nCI/CD YAML files"]
320324
@@ -327,20 +331,19 @@ graph TB
327331

328332
#### Entry Point: `index.ts`
329333

330-
The [`src/index.ts`](https://github.com/verygoodplugins/mcp-automem/blob/b81c63ae8f833feb4f6fb21e795c389f99a5dbe8/src/index.ts) file serves dual purposes based on command-line arguments:
334+
The [`src/index.ts`](https://github.com/verygoodplugins/mcp-automem/blob/946f9e5ed1385b632efd2e5b250d064bcc4295e8/src/index.ts) file serves dual purposes based on command-line arguments:
331335

332336
1. **Server Mode** (no arguments): Launches an MCP server using `StdioServerTransport` from `@modelcontextprotocol/sdk`
333337
2. **CLI Mode** (with arguments): Routes commands to appropriate CLI handlers in `src/cli/`
334338

335339
#### HTTP Client: `automem-client.ts`
336340

337-
The [`src/automem-client.ts`](https://github.com/verygoodplugins/mcp-automem/blob/b81c63ae8f833feb4f6fb21e795c389f99a5dbe8/src/automem-client.ts) file implements the `AutoMemClient` class, providing a typed HTTP interface to the AutoMem backend service.
341+
The [`src/automem-client.ts`](https://github.com/verygoodplugins/mcp-automem/blob/946f9e5ed1385b632efd2e5b250d064bcc4295e8/src/automem-client.ts) file implements the `AutoMemClient` class, providing a typed HTTP interface to the AutoMem backend service.
338342

339343
| Method | HTTP Endpoint | Purpose |
340344
|---|---|---|
341345
| `storeMemory()` | `POST /memory` | Store new memory with content, tags, metadata |
342-
| `recallMemory()` | `GET /recall` | Hybrid search (vector + keyword + tags) |
343-
| `recallMemoryByTag()` | `GET /memory/by-tag` | Tag-only filtering |
346+
| `recallMemory()` | `GET /recall`, or `GET /memory/by-tag` internally when called with `tags` + `exhaustive: true` | Hybrid search (vector + keyword + tags), or tag-only filtering |
344347
| `associateMemories()` | `POST /associate` | Create typed relationships |
345348
| `updateMemory()` | `PATCH /memory/:id` | Update existing memory fields |
346349
| `deleteMemory()` | `DELETE /memory/:id` | Remove memory and embedding |
@@ -354,7 +357,7 @@ The [`src/automem-client.ts`](https://github.com/verygoodplugins/mcp-automem/blo
354357

355358
#### Type Definitions: `types.ts`
356359

357-
The [`src/types.ts`](https://github.com/verygoodplugins/mcp-automem/blob/b81c63ae8f833feb4f6fb21e795c389f99a5dbe8/src/types.ts) file defines TypeScript interfaces for all data structures:
360+
The [`src/types.ts`](https://github.com/verygoodplugins/mcp-automem/blob/946f9e5ed1385b632efd2e5b250d064bcc4295e8/src/types.ts) file defines TypeScript interfaces for all data structures:
358361

359362
- **Configuration types**: `AutoMemConfig`, `MCPServerConfig`, `ClaudeCodeConfig`
360363
- **Memory operation arguments**: `StoreMemoryArgs`, `RecallMemoryArgs`, `AssociateMemoriesArgs`
@@ -413,7 +416,7 @@ The `dist/` directory is generated by TypeScript compilation (`tsc`) and contain
413416
2. **Type declarations** (`.d.ts`) — For TypeScript consumers
414417
3. **Source maps** (`.js.map`) — For debugging compiled code
415418

416-
**TypeScript configuration** ([`tsconfig.json`](https://github.com/verygoodplugins/mcp-automem/blob/b81c63ae8f833feb4f6fb21e795c389f99a5dbe8/tsconfig.json)):
419+
**TypeScript configuration** ([`tsconfig.json`](https://github.com/verygoodplugins/mcp-automem/blob/946f9e5ed1385b632efd2e5b250d064bcc4295e8/tsconfig.json)):
417420

418421
- `outDir: "./dist"` — Output location
419422
- `declaration: true` — Generate `.d.ts` files
@@ -433,7 +436,7 @@ The `dist/` directory is generated by TypeScript compilation (`tsc`) and contain
433436

434437
### Plugins Directory (`plugins/`)
435438

436-
The `plugins/` directory contains a packaged version of the MCP server for Claude Desktop's plugin system. This directory duplicates content from `templates/` to support the `.mcpb` extension format, which requires a self-contained plugin directory with all resources included.
439+
`plugins/automem/` packages AutoMem as an installable Claude Code plugin: `.claude-plugin/plugin.json` (plugin manifest), plus `commands/`, `hooks/`, `scripts/`, and `skills/memory-management/`. A separate top-level `.claude-plugin/marketplace.json` registers the plugin in the Claude Code plugin marketplace. There is no `server/` subdirectory — this is a Claude Code plugin bundle, not a packaged MCP server.
437440

438441
### Configuration Files
439442

@@ -456,13 +459,13 @@ The repository root contains multiple configuration files:
456459

457460
Five files must maintain version consistency (managed by release-please):
458461

459-
1. `package.json` — e.g. `"version": "0.14.0"` (at mcp-automem@b81c63a)
460-
2. `plugins/mcp-automem/server.json` — same version string
462+
1. `package.json` — e.g. `"version": "0.15.0"` (at mcp-automem@946f9e5)
463+
2. `server.json` (repo root) — same version string
461464
3. `manifest.json` — same version string
462-
4. `plugin.json` — same version string
463-
5. `marketplace.json` — same version string
465+
4. `plugins/automem/.claude-plugin/plugin.json` — same version string
466+
5. `.claude-plugin/marketplace.json` — same version string
464467

465-
The [`release-please.yml`](https://github.com/verygoodplugins/mcp-automem/blob/b81c63ae8f833feb4f6fb21e795c389f99a5dbe8/.github/workflows/release-please.yml) workflow automatically updates all five files when creating releases based on conventional commits.
468+
The [`release-please.yml`](https://github.com/verygoodplugins/mcp-automem/blob/946f9e5ed1385b632efd2e5b250d064bcc4295e8/.github/workflows/release-please.yml) workflow automatically updates all five files when creating releases based on conventional commits.
466469

467470
### GitHub Workflows (`.github/`)
468471

0 commit comments

Comments
 (0)