Skip to content
Palimem Docsspec v1.7.0

Scopes

Palimem routes every memory record into one of three scopes: user, session, or repository. Scopes are isolation boundaries, not just labels. A memory_search query in repository scope does not cross into user scope unless you ask it to.

The three scopes

Section titled “The three scopes”

User scope

Section titled “User scope”

Stores facts and preferences that belong to the human developer — not to any specific project.

  • Examples: preferred code style, timezone, recurring preferences, personal shortcuts
  • Namespace: typically the user’s identity or machine name
  • Lifetime: persistent across projects and sessions
  • Who writes: Claude Code hooks (e.g. PreCompact), operator CLIs, explicit agent writes

User scope is where cross-project preferences live. A fact like “prefers strict TypeScript” should be in user scope so all projects benefit.

Session scope

Section titled “Session scope”

Stores ephemeral context for the current coding session — tool failures, scratch observations, turn summaries.

  • Examples: “tried npm run build and got an ENOENT error”, this-session observations
  • Namespace: the workspace or session identifier
  • Lifetime: one session; may be rolled up to repository scope at session end
  • Who writes: the PostToolUseFailure hook, turn summaries, explicit agent writes

Session scope is short-lived by design. It keeps noise out of repository scope and avoids polluting long-term memory with transient debugging context.

Repository scope

Section titled “Repository scope”

Stores facts about the codebase — architecture decisions, team conventions, project state.

  • Examples: “auth provider is OAuth2”, “database is Postgres 16”, “deploy to AWS us-east-1”
  • Namespace: the project or repository name
  • Lifetime: persistent across sessions; the canonical project memory
  • Who writes: explicit agent writes, the PreCompact hook, consolidation proposals

Repository scope is the most important scope for team continuity. Facts written here survive session restarts and are recalled in future sessions.

Scope isolation

Section titled “Scope isolation”

Memory searches respect scope boundaries:

memory_search(query="auth provider", scope="repository", namespace="my-project")
→ [{ value: "OAuth2", topic: "auth", field: "provider" }]
memory_search(query="auth provider", scope="user", namespace="alice")
→ []  ← user scope is a different isolation domain

This prevents scope bleed — the contamination of repository context with user preferences, or session noise entering long-term repository facts.

Namespace

Section titled “Namespace”

Within a scope, the namespace further partitions memory. For repository scope, the namespace is typically the project or repository name. For session scope, it is the session or workspace identifier.

The ai-memory CLI and hooks default the namespace to the workspace folder basename (basename "$PWD"). You can override it with MEMORY_SERVICE_NAMESPACE.

Section titled “Cross-scope search”

To search across all scopes for a given namespace, omit the scope parameter or iterate per scope. The session-start hook injects a bounded multi-scope manifest to give the agent cross-scope context at session start without a runtime cross-scope query.

Scope selection guide

Section titled “Scope selection guide”
Memory type Recommended scope
User preferences, code style user
Current session debugging notes session
Architecture decisions repository
Team conventions repository
One-off scratch observations session
Stable facts about the tech stack repository
Facts that should follow you to other projects user

When in doubt, use repository. Session scope is for transient context you expect to discard. User scope is for preferences that belong to you, not the project.

Scope transitions

Section titled “Scope transitions”

The PreCompact hook (Claude Code) promotes user snippets and custom instructions from session context to repository facts before Claude Code compacts the conversation. This ensures continuity when the context window resets.

The consolidate operator creates promotion proposals that move session beliefs to repository beliefs when evidence is sufficient. Promotion from belief to fact always requires an explicit memory_review accept.

Next steps

Section titled “Next steps”