Skip to content

Commit ea84756

Browse files
codeaholicguycodeaholicguy
committed
Add memory db path config plan
1 parent c0c06ac commit ea84756

File tree

5 files changed

+272
-0
lines changed

5 files changed

+272
-0
lines changed

‎docs/ai/design/feature-memory-db-path-config.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
phase: design
3+
title: System Design & Architecture
4+
description: Resolve memory database path from project config with default fallback
5+
---
6+
7+
# System Design & Architecture
8+
9+
## Architecture Overview
10+
```mermaid
11+
graph TD
12+
ProjectConfig[./.ai-devkit.json] --> ConfigManager
13+
ConfigManager --> Resolver[CLI memory path resolver]
14+
CLI[ai-devkit memory *] --> Resolver
15+
Resolver --> MemoryAPI[@ai-devkit/memory API]
16+
DefaultPath[~/.ai-devkit/memory.db] --> MemoryAPI
17+
MemoryAPI --> DatabasePath[Effective DB path]
18+
DatabasePath --> SQLite[(SQLite memory.db)]
19+
```
20+
21+
- Keep `DEFAULT_DB_PATH` as the baseline fallback in the memory package.
22+
- Add a CLI-owned resolver that can return a project override from `.ai-devkit.json`.
23+
- Pass the resolved path from the CLI into `@ai-devkit/memory` before opening SQLite.
24+
- Leave the standalone `@ai-devkit/memory` MCP server unchanged so it continues using `DEFAULT_DB_PATH`.
25+
26+
## Data Models
27+
- Extend `DevKitConfig` with an optional memory section:
28+
```ts
29+
interface DevKitConfig {
30+
memory?: {
31+
path?: string;
32+
};
33+
}
34+
```
35+
- Extend CLI-to-memory command options with optional `dbPath?: string`.
36+
- Resolver output is either:
37+
- an absolute filesystem path derived from `memory.path`
38+
- `undefined`, which means the memory package falls back to `DEFAULT_DB_PATH`
39+
40+
## API Design
41+
- Add `ConfigManager.getMemoryDbPath(): Promise<string | undefined>` to read project config safely.
42+
- Resolve `memory.path` inside the CLI command layer, not inside `packages/memory`.
43+
- Add optional `dbPath` support to the memory package command APIs used by the CLI:
44+
- `memoryStoreCommand(options)`
45+
- `memorySearchCommand(options)`
46+
- `memoryUpdateCommand(options)`
47+
- Keep `packages/memory/src/server.ts` and the `ai-devkit-memory` binary unchanged in this feature.
48+
49+
## Component Breakdown
50+
- `packages/cli/src/types.ts`
51+
- Add optional `memory.path` typing to project config.
52+
- `packages/cli/src/lib/Config.ts`
53+
- Parse and validate `memory.path` from project config.
54+
- Resolve relative paths against the config file directory.
55+
- `packages/cli/src/commands/memory.ts`
56+
- Load the project config once per command invocation.
57+
- Pass resolved `dbPath` into the imported memory command API.
58+
- `packages/memory/src/database/connection.ts`
59+
- Continue exposing `DEFAULT_DB_PATH`.
60+
- Accept explicit `dbPath` from callers without changing fallback semantics.
61+
- `packages/memory/src/api.ts`
62+
- Accept optional `dbPath` on CLI-facing command option types.
63+
- Call `getDatabase({ dbPath })` so the explicit path only affects CLI-triggered operations that pass it.
64+
- Tests
65+
- Config parsing tests in CLI package.
66+
- Memory command resolution tests in CLI and memory package.
67+
- No standalone MCP server behavior change tests are needed beyond regression confidence.
68+
69+
## Design Decisions
70+
- Keep fallback logic in the memory package and config parsing in the CLI package to preserve clear responsibilities.
71+
- Resolve relative paths from the project root so checked-in config behaves consistently across shells and CI.
72+
- Treat missing, blank, or non-string `memory.path` as unset and fall back silently to `DEFAULT_DB_PATH` to preserve backward compatibility.
73+
- Keep the package boundary intact by passing `dbPath` explicitly from the CLI rather than making `packages/memory` depend on `ConfigManager`.
74+
- Apply the configured path to `store`, `search`, and `update` so CLI memory subcommands stay consistent.
75+
76+
## Non-Functional Requirements
77+
- No change to default behavior for projects without `memory.path`.
78+
- No additional network or external service dependency.
79+
- Path resolution must be deterministic across macOS and Linux path semantics already supported by Node's `path` module.
80+
- Database initialization and schema migration behavior remain unchanged once the final path is selected.
81+
- Standalone `@ai-devkit/memory` server startup and runtime behavior remain unchanged in this feature.

‎docs/ai/implementation/feature-memory-db-path-config.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
phase: implementation
3+
title: Implementation Guide
4+
description: Implementation notes for project-configurable memory database paths
5+
---
6+
7+
# Implementation Guide
8+
9+
## Development Setup
10+
- Use the feature worktree `feature-memory-db-path-config`.
11+
- Install dependencies with `npm ci` from the worktree root.
12+
13+
## Code Structure
14+
- Config shape and parsing live in the CLI package.
15+
- Effective database path selection must be shared by all memory entry points.
16+
17+
## Implementation Notes
18+
### Core Features
19+
- Add typed support for `memory.path` in project config.
20+
- Resolve relative configured paths from the project root.
21+
- Pass the resolved path into every memory operation entry point.
22+
23+
### Patterns & Best Practices
24+
- Keep `DEFAULT_DB_PATH` as the fallback constant.
25+
- Avoid duplicating path-resolution logic across command handlers and server code.
26+
27+
## Integration Points
28+
- `.ai-devkit.json`
29+
- `ConfigManager`
30+
- memory CLI command adapters
31+
- memory MCP server
32+
33+
## Error Handling
34+
- Invalid or absent `memory.path` should not break memory commands; fall back to the default path.
35+
36+
## Performance Considerations
37+
- Path resolution should happen once per command/tool invocation before opening the database.
38+
39+
## Security Notes
40+
- Treat `memory.path` as a filesystem path only; no shell execution or interpolation.

‎docs/ai/planning/feature-memory-db-path-config.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
phase: planning
3+
title: Project Planning & Task Breakdown
4+
description: Task breakdown for project-configurable memory database paths
5+
---
6+
7+
# Project Planning & Task Breakdown
8+
9+
## Milestones
10+
- [ ] Milestone 1: Project config schema and parsing support `memory.path`
11+
- [ ] Milestone 2: Memory command and server flows consume resolved database path
12+
- [ ] Milestone 3: Tests cover configured path and fallback behavior
13+
14+
## Task Breakdown
15+
16+
### Phase 1: Config Support
17+
- [ ] Task 1.1: Extend `packages/cli/src/types.ts` to type optional `memory.path`
18+
- [ ] Task 1.2: Add `ConfigManager.getMemoryDbPath()` in `packages/cli/src/lib/Config.ts`
19+
- [ ] Task 1.3: Add unit tests for project config parsing, including missing, invalid, absolute, and relative path cases
20+
21+
### Phase 2: Memory Path Wiring
22+
- [ ] Task 2.1: Introduce a shared path-resolution flow that combines project config override with `DEFAULT_DB_PATH`
23+
- [ ] Task 2.2: Update `packages/memory/src/api.ts` and related entry points so store/search/update use the resolved path consistently
24+
- [ ] Task 2.3: Update the memory MCP server startup/tool handling to honor the same project-configured database path
25+
26+
### Phase 3: Verification
27+
- [ ] Task 3.1: Add or update CLI tests covering memory commands with configured `memory.path`
28+
- [ ] Task 3.2: Add or update memory package tests covering fallback to `~/.ai-devkit/memory.db`
29+
- [ ] Task 3.3: Run targeted verification for docs lint and relevant automated tests
30+
31+
## Dependencies
32+
- Task 1.1 precedes Task 1.2 because config typing should match the new parser surface.
33+
- Task 1.2 precedes Task 2.1 and Task 2.2 because runtime resolution depends on the config accessor.
34+
- Task 2.1 should land before Task 2.2 and Task 2.3 so all memory entry points share one resolution rule.
35+
- Verification tasks depend on both config support and runtime wiring being complete.
36+
37+
## Timeline & Estimates
38+
- Phase 1: Small, low-risk change
39+
- Phase 2: Medium effort because path selection currently sits below config loading boundaries
40+
- Phase 3: Small to medium effort depending on current test coverage for memory command setup
41+
42+
## Risks & Mitigation
43+
- Risk: CLI commands honor config but MCP server still uses the default database.
44+
Mitigation: Define one shared resolver and cover both entry points in tests.
45+
- Risk: Relative paths resolve from process cwd instead of project root.
46+
Mitigation: Resolve from the config file directory and add explicit unit tests.
47+
- Risk: Invalid config values break existing users.
48+
Mitigation: Treat invalid values as unset and retain `DEFAULT_DB_PATH`.
49+
50+
## Resources Needed
51+
- Existing config loading utilities in `packages/cli/src/lib/Config.ts`
52+
- Existing database connection behavior in `packages/memory/src/database/connection.ts`
53+
- Existing memory command tests in `packages/cli/src/__tests__/commands/memory.test.ts`

‎docs/ai/requirements/feature-memory-db-path-config.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
phase: requirements
3+
title: Requirements & Problem Understanding
4+
description: Allow project config to override the default memory database path
5+
---
6+
7+
# Requirements & Problem Understanding
8+
9+
## Problem Statement
10+
- Memory storage currently defaults to `~/.ai-devkit/memory.db` via `packages/memory/src/database/connection.ts`.
11+
- Projects cannot pin memory storage to a repo-specific database, so contributors working in the same repository may read and write different global state.
12+
- Users who want isolated project memory have no supported configuration path in `.ai-devkit.json`.
13+
14+
## Goals & Objectives
15+
- Allow project `.ai-devkit.json` to define `memory.path`.
16+
- Keep the existing default database path as `~/.ai-devkit/memory.db` when no project override is configured.
17+
- Make memory commands use the configured project path consistently for store, search, and update flows.
18+
- Scope the change to `ai-devkit` project commands and avoid changing standalone `@ai-devkit/memory` package behavior.
19+
20+
## Non-Goals
21+
- Adding a global `memory.path` override in `~/.ai-devkit/.ai-devkit.json`.
22+
- Redesigning unrelated `.ai-devkit.json` sections.
23+
- Changing the default database filename or directory.
24+
- Making standalone `@ai-devkit/memory` automatically read project `.ai-devkit.json`.
25+
26+
## User Stories & Use Cases
27+
- As a project maintainer, I can commit `"memory": { "path": ".ai-devkit/project-memory.db" }` to `.ai-devkit.json` so everyone on the repository uses the same project-local memory database.
28+
- As a developer without project memory config, I continue using `~/.ai-devkit/memory.db` with no behavior change.
29+
- As a user running `ai-devkit memory search`, `store`, or `update` inside a configured project, I want all commands to resolve the same configured database path automatically.
30+
- As a user running the standalone `@ai-devkit/memory` MCP server directly, I continue using its package default path unless a later feature adds separate config support.
31+
32+
## Success Criteria
33+
- Project `.ai-devkit.json` accepts a `memory.path` string.
34+
- When `memory.path` is present in project config, `ai-devkit memory` operations use that path instead of `~/.ai-devkit/memory.db`.
35+
- When `memory.path` is absent, empty, or invalid, memory operations fall back to `~/.ai-devkit/memory.db`.
36+
- Relative configured paths are resolved deterministically from the project root containing `.ai-devkit.json`.
37+
- Tests cover configured path resolution and default fallback behavior.
38+
- Standalone `@ai-devkit/memory` behavior remains unchanged in this feature.
39+
40+
## Constraints & Assumptions
41+
- `ConfigManager` already owns project `.ai-devkit.json` loading in `packages/cli/src/lib/Config.ts`.
42+
- The current memory package hard-codes the default path in `packages/memory/src/database/connection.ts`; implementation must preserve that default for non-project-aware callers.
43+
- The project config shape currently allows additive extension without a broader schema migration.
44+
- The configured path should remain a plain filesystem path string; no environment-variable expansion is required unless existing config code already supports it.
45+
- `packages/memory` should not gain a dependency on the CLI package just for this feature.
46+
47+
## Questions & Open Items
48+
- The config key will be `memory.path` in project `.ai-devkit.json`.
49+
- Relative paths will be interpreted relative to the directory containing `.ai-devkit.json`, not the shell's current working directory.
50+
- Scope decision: only `ai-devkit` project commands will honor `memory.path`; standalone `@ai-devkit/memory` is out of scope.
51+
- No additional blocking questions remain for implementation.

‎docs/ai/testing/feature-memory-db-path-config.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
phase: testing
3+
title: Testing Strategy
4+
description: Testing plan for project-configurable memory database paths
5+
---
6+
7+
# Testing Strategy
8+
9+
## Test Coverage Goals
10+
- Cover 100% of new and changed code related to config parsing and path resolution.
11+
- Verify both configured-path and default-path flows.
12+
13+
## Unit Tests
14+
### Config parsing
15+
- [ ] Reads `memory.path` when it is a non-empty string
16+
- [ ] Ignores missing, blank, and non-string `memory.path`
17+
- [ ] Resolves relative `memory.path` from the project config directory
18+
19+
### Memory command resolution
20+
- [ ] `memory store` uses configured path when project config exists
21+
- [ ] `memory search` uses configured path when project config exists
22+
- [ ] `memory update` uses configured path when project config exists
23+
- [ ] Commands fall back to `~/.ai-devkit/memory.db` when no project override exists
24+
25+
## Integration Tests
26+
- [ ] Memory MCP server tool calls use the same resolved path as CLI commands
27+
- [ ] Schema initialization still succeeds when the configured path points to a new file
28+
29+
## End-to-End Tests
30+
- [ ] Manual smoke test with a checked-in `.ai-devkit.json` using a repo-local memory DB
31+
32+
## Test Data
33+
- Temporary project directories with generated `.ai-devkit.json`
34+
- Temporary database file paths for isolated runs
35+
36+
## Test Reporting & Coverage
37+
- Run targeted CLI and memory package tests plus docs lint for this feature
38+
39+
## Manual Testing
40+
- Confirm a repo-local configured DB file is created on first write
41+
- Confirm commands revert to the home-directory database when config is removed
42+
43+
## Performance Testing
44+
- No dedicated performance testing required beyond regression confidence
45+
46+
## Bug Tracking
47+
- Watch for regressions where one memory entry point still opens `~/.ai-devkit/memory.db`

0 commit comments

Comments
 (0)