configure_scope
Configure Scope ·writes · non-destructive · idempotent · closed-world
Bind a project name to a scope (‘work’ or ‘personal’) with optional aliases. Future memories
auto-inherit this scope when tagged with the project or an alias.
User-configured mappings take precedence over the default scope config.
Aliases are alternative project names that resolve to this project.
For example, aliases=[“dev”, “engineering”] with project=“consulting”
means memories tagged with project “dev” or “engineering” inherit the
scope configured for “consulting”.
Returns: str
Source: backend/src/engram/mcp/tools/memory/lifecycle.py
Parameters
Project name (case-insensitive, will be lowercased)
Life context scope — ‘work’ or ‘personal’
Optional list of alias names that should resolve to this project
get_memory_sharing
Get Memory Sharing ·read-only · non-destructive · idempotent · closed-world
Inspect memory share state for one memory, one scope, or the caller.
Read-only counterpart to set_memory_sharing. Pass exactly one of
memory_id (effective share state per accepted pairing), scope
(active scope-share rules owned by the caller), or incoming=True
(active shares received by the caller). With no arguments, defaults to
incoming=True so an agent without context still gets a usable answer.
Pass teams=True together with memory_id to list the team shares the
caller has granted on that memory instead of the pairwise share state.
Returns: str
Source: backend/src/engram/mcp/tools/memory/sharing.py
Parameters
Owned memory id to inspect. Returns explicit + scope-derived + denial state for each accepted pairing (or team shares when
teams=True).Memory scope (personal or work) to list active scope-share rules the caller has granted on. Mutually exclusive with memory_id.
When True (default if no other arg), lists active shares the caller has received.
When True with
memory_id, list team shares on that memory.reapply_scope_mappings
Reapply Scope Mappings ·writes · non-destructive · idempotent · closed-world
Re-apply the current scope→project mapping to existing memories whose scope is stale.
Useful after adding or changing scope mappings via configure_scope.
Returns: str
Source: backend/src/engram/mcp/tools/memory/lifecycle.py
This tool takes no parameters.
remember
Save Memory ·writes · non-destructive · non-idempotent · closed-world
Persist a new memory of any canonical type.
Canonical types are: decision, commitment, blocker, preference, pattern,
note, event, fact. Writes a fresh memory for retrieval across future
sessions — to look up existing memories use search; to change a
memory’s type or status use update_memories.
Consolidation: near-duplicates merge into the existing row. The
response carries consolidated_into=<memory_id> and no
memory.created event fires — treat the token as authoritative and
read the consolidated row synchronously. Use mode='new' to bypass.
Returns: str
Source: backend/src/engram/mcp/tools/memory/remember.py
Parameters
Short topic label.
The memory content to persist.
Optional tags for categorization.
One of: decision, commitment, blocker, preference, pattern, note, event, fact. Legacy compatibility: context -> note.
Optional project name.
Optional urgency level.
Optional ISO 8601 expiration timestamp.
Optional ISO 8601 due date for commitments.
‘personal’ or ‘work’. Auto-derived from project if omitted.
Memory origin. Defaults to ‘mcp’ (AI agent via MCP). Other values: ‘manual’ (dashboard), ‘hook’ (PostToolUse auto-capture), ‘integration’ (third-party sync), ‘onboarding’. Reserved: ‘auto’.
‘open’ (default), ‘waiting’ (blocked on external input), or ‘scheduled’ (intentionally deferred).
Optional JSON for recurring commitments. Keys: frequency, interval, end_date.
Consolidation intent. One of: ‘auto’ (default), ‘merge’ (force merge above similarity threshold), ‘cluster’ (skip merge; link via cluster_members), ‘new’ (skip both merge and cluster). The 60-second hash-dedup window applies to every mode.
Mark as a standing reference retrieved as one unit instead of treated as chunkable source material.
content_chunks.id when promoting an indexed chunk. Implies atomic=True.
Subject entity for fact writes (mutually optional with entity_name). Must reference an existing entity; an unknown ID is rejected.
Subject entity for fact writes (mutually optional with entity_id). Resolves an existing entity by name/alias, or auto-creates one when the name is new so facts can be written about brand-new subjects (#4716).
Fact attribute for explicit fact writes.
Fact value for explicit fact writes.
Optional fact validity start.
Optional fact validity end.
Mark a fact as immutable so it is not auto-superseded.
Delegated commitment owner UUID. Reads use COALESCE(owner_id, user_id), so unset preserves owner=creator.
Free-text “who is this promise to” string.
Optional ISO 8601 timestamp for next surfacing.
FK to a memory this one supersedes (forward-pointing decision lifecycle).
One of: plan, task, follow_up, review, release, migration, integration_task, recurring. DB CHECK enforces.
Optional JSON string of structured per-type metadata. Blockers must include
blocks_memory_id (int) or blocked_item (>=3 chars).remove_scope_mapping
Remove Scope Mapping ·writes · destructive · idempotent · closed-world
Remove a project→scope mapping created via configure_scope (teardown).
Deletes the user’s user_scope_config row for project along with any
scope_aliases that resolve to it. Owner-scoped: only the caller’s own
mappings are touched. Existing memories keep their current scope —
removing a mapping only stops future auto-inheritance for the project.
Returns: str
Source: backend/src/engram/mcp/tools/memory/lifecycle.py
Parameters
Project name whose mapping should be removed (case-insensitive).
set_memory_sharing
Set Memory Sharing ·writes · destructive · idempotent · closed-world
Share, deny, allow, or revoke paired-user OR team memory access on one tool.
Replaces the legacy share_memory / revoke_memory_share / set_memory_scope_share
/ set_memory_scope_denial split. Mode semantics:
share: grant access.target_kind='memory'shares one owned memory by id;target_kind='scope'enables (or disables whenenabled=False) a scope-default share for personal or work.deny: install a per-memory denial that blocks inherited scope sharing for one recipient.target_kindmust bememory.allow: remove a previously installed per-memory denial (inverse ofdeny).target_kindmust bememory.revoke: revoke an active explicit memory share byshare_id.target_kindandtarget_idare ignored but kept in the signature so writers can call the tool uniformly.
share / deny / allow): pass one of
shared_with_email, shared_with_id, or pairing_id for a paired
user, OR team_id to target a whole team. Passing both
shared_with_email and shared_with_id together is rejected as
ambiguous — pick one. pairing_id may accompany either as a
disambiguator when a user has multiple accepted pairings. revoke is
intentionally keyed by share_id only (returned by the share
response); the share_id is unambiguous, so email/pairing routing doesn’t
apply.
Team mode (team_id set): shares route to the team tables instead of the
pairwise ones. share + memory grants the team per-memory access;
share + scope grants the whole scope (toggle with enabled); deny
/ allow install or remove a user-level hole-punch (shared_with_id is
the denied member); revoke revokes a per-memory team share by its
team_share_id passed in share_id. The caller must own the memory and
be an active admin of the team.
Returns: str
Source: backend/src/engram/mcp/tools/memory/sharing.py
Parameters
One of share, deny, allow, revoke.
memory or scope. Ignored when mode=‘revoke’.
Memory id (as str) for memory targets; scope name for scope targets; placeholder for revoke.
UUID of the paired recipient (pairwise mode) or the member to deny (team
deny/allow mode). Mutually exclusive with shared_with_email.Email of the paired recipient. Mutually exclusive with
shared_with_id. Accepted on every pairwise mode that takes a recipient (share, deny, allow).Optional accepted pairing UUID for disambiguation when the current user has more than one accepted pairing with the same recipient. Sufficient on its own when unambiguous.
Required for mode=‘revoke’. UUID of the memory_shares row (or memory_team_shares row when
team_id is set) returned by a prior share response.UUID of a team to target instead of a paired user. When set, all modes route to the team-scoped share tables.
When mode=‘share’ and target_kind=‘scope’, False disables an existing scope share. Ignored otherwise.
update_memories
Update Memories ·writes · destructive · idempotent · closed-world
Update state on one or more memories. At least one of memory_type or
status must be provided. Content is not modified.
memory_typeaccepts canonical types (decision, commitment, blocker, preference, pattern, note, event, fact); legacy aliases (e.g.context) are normalized.statusaccepts"open"or"archived". Archived memories are hidden from default search; reopen by calling withstatus="open". To resolve/reopen commitments, use theresolve/unresolvetools (they manageresolution_noteandresolved_at).
str
Source: backend/src/engram/mcp/tools/memory/lifecycle.py
Parameters
List of memory IDs to update. Empty list is rejected.
Optional new memory_type. Validated against the canonical set; legacy aliases normalized.
Optional new status. One of
"open" or "archived".