The server's "session" is a project's whole memory scope, but nothing defines it and the name reads as a conversation #1812

The server's session is a project's whole memory scope, but nothing in the code or the docs says so. Everywhere else, inside this repository and outside it, "session" means one conversation. People and coding agents read the server's session as a conversation and reach wrong conclusions from it. File references are at main 6fe7c2f.

What the server's session is

• The v2 API builds the session key from the project: session_key = f"{spec.org_id}/{spec.project_id}", in six routes of packages/server/src/memmachine_server/server/api_v2/router.py (the first at line 914) and in api_v2/service.py:45.
• That key names the session's configuration row and its short-term memory row (common/session_manager/session_data_manager_sql_impl.py:68 and :87), and the event backend's long-term memory partition (partition_key_for_session(config.session_id), episodic_memory/long_term_memory/service_locator.py:106).
• So one session holds every conversation a caller writes into the project, for the project's whole life, and one short-term summary covers all of them.

Where the same word means a conversation

• The API reference's examples put a conversation id in metadata under the same name: the filter example metadata.user_id=123 AND metadata.session_id=abc (packages/common/src/memmachine_common/api/doc.py:625), and the set type example ["user_id", "session_id"], "grouped by user and session" (doc.py:535).
• The configuration docs set session_key: user-session-id in their examples (docs/open_source/configuration.mdx:76), which reads as one user's conversation.
• The Google ADK integration stores each ADK session, which is a conversation, so that it "can be recalled by other sessions" (docs/install_guide/integrate/Google_ADK.mdx:89).
• The event model on the horizontal-scaling branch gives every event a session_id, described as "a conversation's own timeline" ([event memory 6/7] Add sessions to EventMemory (port of #1597's session half) #1715), inside a partition that is itself keyed by the server's session. The v2 adapter puts all of its events in one reserved session, memmachine_default, because a server session carries no conversation id.

What the code and docs say about it

• Every configuration field that carries the key is described as "Session identifier" and nothing more (common/configuration/episodic_config.py:77, :104, :181, :207, and :274). The configuration docs call it a "Unique session identifier for episodic ingestion and context tracking" (configuration.mdx:128).
• The episode model's session_key is "Session key associated with the episode." (doc.py:100), and SessionDataManager is an "Interface for managing session data and short-term memory."
• CONFIGURE_EPISODIC_MEMORY (doc.py:1314) mentions a "project session", the closest thing to a definition, and then says short-term memory "maintains recent context for the current session", which reads as a conversation.
• No docstring, comment, or doc page says that a session is a project or that it holds many conversations. [Feat]: Server tech debt resolution wishlist #1297 already lists "session data manager's responsibilities are not well-defined".

Misreadings it has caused

By users:

• [Docs]: How to structure Memory (chat session, across chat session) #644: an n8n node author used each n8n chat session as a project, since v2 has no conversation-level session. The reply on the issue was to separate memory by org and project and put the conversation id in metadata.
• [Bug]: API v2 Episodic Summary does not support metadata-based session isolation #860: a user expected each conversation in a project to get its own episodic summary. The summary belongs to the server's session, so every conversation in the project shares it.

By coding agents working on this repository:

• 2026-09-01: an agent inferred from partition_key_for_session(config.session_id) that a session is one conversation and an isolation boundary, and used that to justify the scale argument in the first version of Commit Qdrant to payload-partitioned multitenancy: drop per-collection shard keys, retire the in-process lock table, recover fencing and reclamation #1564. The body was rewritten in terms of tenants.
• 2026-10-09: in the review of [user properties 2/2] Remove per-project filterable properties (port of #1606) #1670, an agent argued that partitions keyed by session each hold one conversation, so filter match sets stay small and vector store indexes are rarely needed. A partition holds a whole project, and the conclusion was reversed.

What would resolve it

Either of these:

• Define the term everywhere it is created or stored: the v2 router, SessionDataManager, the configuration fields, the episode model, and the configuration docs. A session is a project's memory scope, it holds many conversations, and a conversation id belongs in metadata.
• Rename the server's session to a word that does not read as a conversation, and keep "session" for the conversation the event model uses. The v2 API exposes session_key on episodes (packages/common/src/memmachine_common/api/spec.py:111), so a rename reaches the API.

🤖 Written by Claude Code (Claude Opus 5.5) on behalf of @edwinyyyu.