Workspaces

Workspaces

Workspaces provide tenant isolation for memories. Each workspace has completely independent:

• Memory store with its own vector indices
• Relationship graph
• Session history
• Configuration and settings

Creating Workspaces

workspace = await client.create_workspace("my-project")

const workspace = await client.createWorkspace("My Project", {
  embedding_model: "text-embedding-3-small",
  default_importance: 0.5,
});

Using Workspaces

Set the workspace at client initialization:

client = MemoryLayerClient(
    base_url="http://localhost:61001",
    workspace_id="my-project"
)

All subsequent operations are scoped to that workspace.

The _default Workspace

Every MemoryLayer instance ships with a built-in _default workspace. When no workspace is specified in a request, memories are stored in and recalled from _default. This makes single-project setups zero-configuration — just start the server and begin storing memories.

# No workspace_id specified — uses _default
memory = await client.remember("Project uses FastAPI")

The _global Workspace

The _global workspace is a special cross-workspace shared store. Memories placed in _global are automatically included when recalling from any workspace (unless explicitly excluded). Use it for organization-wide knowledge that should be accessible everywhere:

# Store shared knowledge in _global
await client.remember(
    content="Company coding standard: use type hints in all Python code",
    workspace_id="_global"
)

# Recall from project workspace — _global memories are included automatically
results = await client.recall(
    query="coding standards",
    workspace_id="my-project"
)

During recall, memories from different scopes receive locality boosts:

Scope	Default Boost	Description
Same context	1.5x	Memories in the same context as the query
Same workspace	1.2x	Memories in the same workspace
Global workspace	1.0x	Memories from _global (no boost)

Workspace Isolation

Memories in different workspaces are completely separate:

Workspace: "frontend-app"          Workspace: "backend-api"
├── "Uses React 18"                ├── "Uses FastAPI"
├── "Prefers Tailwind CSS"         ├── "PostgreSQL for persistence"
└── "Dark mode by default"         └── "JWT authentication"

Isolation Patterns

Pattern	Workspace Strategy	When to Use
Per-project	One workspace per git repository	Teams working on separate codebases
Per-user	One workspace per user account	Personal knowledge management
Per-environment	Separate dev/staging/prod workspaces	Environment-specific configurations
Per-agent	Each agent instance gets its own workspace	Multi-agent systems with independent memory

Per-User Isolation

# Each user gets their own workspace
user_workspace = f"user-{user_id}"
await client.create_workspace(user_workspace)

session = await client.create_session(
    workspace_id=user_workspace,
    ttl_seconds=3600
)

Per-Environment Isolation

import os

env = os.getenv("ENVIRONMENT", "dev")
workspace_id = f"my-app-{env}"  # my-app-dev, my-app-staging, my-app-prod

client = MemoryLayerClient(
    base_url="http://localhost:61001",
    workspace_id=workspace_id
)

Workspace Settings

Each workspace can be configured with settings that control memory behavior:

workspace = await client.create_workspace(
    name="my-project",
    settings={
        "default_importance": 0.5,
        "decay_enabled": True,
        "decay_rate": 0.01,
        "embedding_model": "text-embedding-3-small",
        "session_auto_commit": True,
    }
)

Available settings include:

Setting	Default	Description
default_importance	0.5	Default importance for new memories
decay_enabled	true	Enable importance decay over time
decay_rate	0.01	Daily decay rate
embedding_model	text-embedding-3-small	Embedding model to use
session_auto_commit	true	Auto-commit working memory on session end

Workspace Export and Import

Export workspace data for backup, migration, or sharing:

# Export via REST API
curl http://localhost:61001/v1/workspaces/my-project/export \
  -o workspace-export.json

# Import into another instance
curl -X POST http://localhost:61001/v1/workspaces/my-project/import \
  -H "Content-Type: application/json" \
  -d @workspace-export.json

The export format includes all memories and associations in a versioned JSON envelope:

{
  "version": "1.0",
  "exported_at": "2025-01-15T10:30:00Z",
  "workspace_id": "my-project",
  "memories": [...],
  "associations": [...],
  "total_memories": 150,
  "total_associations": 45
}

During import, duplicate memories (by content hash) are automatically skipped.

Workspace Deletion

Delete a workspace and all its contents:

curl -X DELETE http://localhost:61001/v1/workspaces/my-project

Caution

Workspace deletion removes all memories, associations, and sessions within the workspace. This operation cannot be undone.

Auto-Detection (MCP Server)

The MCP server automatically detects the workspace from your project:

1. Git remote origin URL — extracts repo name
2. Git root directory name
3. Current working directory name

~/code/my-app/        → workspace: "my-app"
~/code/api-server/    → workspace: "api-server"

Workspace Schema

Each workspace has a schema defining available relationship types and memory subtypes:

schema = await client.get_workspace_schema("ws_123")
print(schema["relationship_types"])   # Available relationship types
print(schema["memory_subtypes"])      # Available subtypes

Organizing Memories

Within a workspace, use tags for fine-grained classification of memories:

memory = await client.remember(
    content="JWT tokens expire after 1 hour",
    tags=["auth", "jwt", "security"]
)

# Filter by tags during recall
results = await client.recall(
    query="authentication setup",
    tags=["auth"]
)

Tags are flexible, per-memory labels that support AND-logic filtering during recall.