📋 Pre-flight Checks
🔍 Problem Description
Engram uses a single global database (~/.engram/engram.db) for all projects and conversations. When working across multiple unrelated projects, all memories get mixed together in the same DB — making context less relevant and harder to scope.
There's no way to configure project-specific memory isolation without manually setting ENGRAM_DATA_DIR before every session, which is cumbersome and error-prone.
💡 Proposed Solution
Add a centralized project config at ~/.engram/config.json that maps working directories to dedicated databases.
When engram mcp (or any command) starts, it reads the CWD and looks it up in the config. If there's a match, it uses that project's database instead of the global one. If no match is found, it falls back to the global ~/.engram/engram.db.
New config format (~/.engram/config.json)
{
"projects": [
{
"path": "/home/user/my-app",
"data_dir": "/home/user/my-app/.engram"
},
{
"path": "/home/user/work/client-x",
"data_dir": "/home/user/work/client-x/.engram"
}
]
}
New CLI commands
# Add current directory to project config (sets data_dir to CWD/.engram)
engram project add
# List all configured projects
engram project list
# Remove current directory from project config
engram project remove
Resolution priority (highest → lowest)
| Priority |
Source |
Notes |
| 1 |
ENGRAM_DATA_DIR env var |
Existing — unchanged |
| 2 |
~/.engram/config.json project match |
New |
| 3 |
~/.engram global fallback |
Existing — unchanged |
Behavior details
- Match is exact — CWD must equal
project.path
- If
data_dir doesn't exist → created automatically on first use (.engram/ inside the project)
- DB filename stays
engram.db — only the directory changes
engram project add reads CWD and sets data_dir to CWD/.engram
engram project add is idempotent — running it twice does not duplicate the entry
📦 Affected Area
CLI (commands, flags)
🔄 Alternatives Considered
Setting ENGRAM_DATA_DIR per project via shell aliases or .envrc files works, but requires manual setup per machine and isn't portable or discoverable across teammates.
📎 Additional Context
This follows the same pattern as other tools that support per-project config (e.g. .nvmrc, .tool-versions, opencode.json) — a single place to configure behavior without per-machine setup.
The implementation touches only cmd/engram/ — no changes to internal/store/ are required since store.New already accepts an arbitrary DataDir.
Files expected to change
| File |
Change |
cmd/engram/project.go |
New file — EngramConfig, ProjectEntry structs, cmdProject* functions, config read/write helpers |
cmd/engram/project_test.go |
New file — unit tests for all new behavior |
cmd/engram/main.go |
Add osGetwd seam, project config resolution in startup flow, case "project" dispatch, updated usage text |
📋 Pre-flight Checks
status:approvedbefore a PR can be opened🔍 Problem Description
Engram uses a single global database (
~/.engram/engram.db) for all projects and conversations. When working across multiple unrelated projects, all memories get mixed together in the same DB — making context less relevant and harder to scope.There's no way to configure project-specific memory isolation without manually setting
ENGRAM_DATA_DIRbefore every session, which is cumbersome and error-prone.💡 Proposed Solution
Add a centralized project config at
~/.engram/config.jsonthat maps working directories to dedicated databases.When
engram mcp(or any command) starts, it reads the CWD and looks it up in the config. If there's a match, it uses that project's database instead of the global one. If no match is found, it falls back to the global~/.engram/engram.db.New config format (
~/.engram/config.json){ "projects": [ { "path": "/home/user/my-app", "data_dir": "/home/user/my-app/.engram" }, { "path": "/home/user/work/client-x", "data_dir": "/home/user/work/client-x/.engram" } ] }New CLI commands
Resolution priority (highest → lowest)
ENGRAM_DATA_DIRenv var~/.engram/config.jsonproject match~/.engramglobal fallbackBehavior details
project.pathdata_dirdoesn't exist → created automatically on first use (.engram/inside the project)engram.db— only the directory changesengram project addreads CWD and setsdata_dirtoCWD/.engramengram project addis idempotent — running it twice does not duplicate the entry📦 Affected Area
CLI (commands, flags)
🔄 Alternatives Considered
Setting
ENGRAM_DATA_DIRper project via shell aliases or.envrcfiles works, but requires manual setup per machine and isn't portable or discoverable across teammates.📎 Additional Context
This follows the same pattern as other tools that support per-project config (e.g.
.nvmrc,.tool-versions,opencode.json) — a single place to configure behavior without per-machine setup.The implementation touches only
cmd/engram/— no changes tointernal/store/are required sincestore.Newalready accepts an arbitraryDataDir.Files expected to change
cmd/engram/project.goEngramConfig,ProjectEntrystructs,cmdProject*functions, config read/write helperscmd/engram/project_test.gocmd/engram/main.goosGetwdseam, project config resolution in startup flow,case "project"dispatch, updated usage text