feat: add workspace-based memory isolation

[djonatas]

Summary

This PR adds support for workspace-based memory isolation, allowing users to keep memory data completely separate between different clients, organizations, or project groups.

Closes #1318

Motivation

Currently, claude-mem stores all observations and session data in a single global SQLite database. While the project column allows filtering by project name, there's no true isolation between different organizational contexts.

Real-world use case: A consultant working with multiple clients needs to ensure that:

• Context from Client A's projects doesn't leak into Client B's sessions
• Architectural decisions and code patterns stay within their respective client boundaries
• Compliance requirements (NDAs, data separation) are met

Changes

New Files

File	Description
src/utils/workspace.ts	Workspace detection and routing logic
src/shared/paths-workspace.ts	Workspace-aware path resolution
src/services/worker/WorkspaceDatabaseManager.ts	Multi-database connection manager
src/cli/handlers/session-init-workspace.ts	Workspace-aware session initialization
docs/workspace-isolation.md	Complete documentation
tests/unit/workspace.test.ts	23 unit tests
tests/integration/workspace-isolation.test.ts	13 integration tests

Test Coverage

Total: 36 tests passing

npx vitest run tests/unit/workspace.test.ts tests/integration/workspace-isolation.test.ts

✓ tests/unit/workspace.test.ts (23 tests)
✓ tests/integration/workspace-isolation.test.ts (13 tests)

Test Files: 2 passed
Tests: 36 passed

Configuration

Environment Variable

export CLAUDE_MEM_WORKSPACE_ROOTS="/path/to/ClientA,/path/to/ClientB"

Data Layout

~/.claude-mem/
├── workspaces/
│   ├── clienta/
│   │   ├── claude-mem.db
│   │   └── vector-db/
│   └── clientb/
│       ├── claude-mem.db
│       └── vector-db/
├── claude-mem.db          # Global fallback
└── settings.json

Key Features

1. Complete Isolation: Separate SQLite databases per workspace
2. Shared Context Within Workspace: Projects in the same workspace share memory (desirable for related projects)
3. Automatic Detection: Workspace detected from cwd passed by hooks
4. Graceful Fallback: Paths outside configured workspaces use global database

Backwards Compatibility

• No configuration = No change: If CLAUDE_MEM_WORKSPACE_ROOTS is not set, behavior is identical to current version
• Existing data preserved: Global database continues to work
• No migration required: Feature is additive

Checklist

• Unit tests added (23 tests)
• Integration tests added (13 tests)
• Documentation added
• Backwards compatible
• No breaking changes

[RawSalmon69]

Came across this repo, and was wondering how claude would differentiate if I have multiple claude code sessions running on different project. This feature is a must have imo. Thank you for implementing it

[djonatas]

Thanks for the kind words! 🙏

To answer your question about how claude-mem differentiates between sessions:

Without this feature (current behavior)

• All sessions write to a single global ~/.claude-mem/claude-mem.db
• A project column stores the project path for filtering, but there's no true isolation
• Memory from Project A could theoretically influence context retrieval in Project B

With workspace isolation (this PR)

• You set CLAUDE_MEM_WORKSPACE_ROOTS to define workspace boundaries
• Each workspace gets its own completely separate SQLite database
• Sessions automatically detect which workspace they're in based on cwd
• Zero cross-contamination between workspaces

Example setup

export CLAUDE_MEM_WORKSPACE_ROOTS="/home/me/work/clientA,/home/me/work/clientB"

Now when you're working in /home/me/work/clientA/project1, all memory goes to ~/.claude-mem/workspaces/clienta/claude-mem.db. Projects outside defined workspaces fall back to the global database.

Feel free to try it out once merged and let us know if you have any feedback!