Workspace Knowledge & Memory

Locus has two local knowledge systems with different jobs:

System	Purpose	Stored data
Workspace Search Index	Find relevant material in project files.	Eligible file chunks, paths, line ranges, hashes, FTS5 terms, and optional local vectors.
Approved memory	Carry eligible preferences, facts, decisions, procedures, and relationships into future work.	Encrypted memory payloads, review state, scope, provenance, confidence, validity, and optional encrypted vectors.

info

Indexing a file does not turn it into memory. A memory suggestion is not recallable until you approve it.

The user-facing memory flow

1. Agent suggests. A clear preference, fact, decision, procedure, or relationship enters the Inbox as a candidate.
2. You review. Approve, edit, reject, keep both sides of a conflict, or replace an older item.
3. Relevant recall. Only approved, eligible memories can be retrieved. Locus explains why each item matched.

Candidates expire after 30 days if they are not approved. This keeps transient suggestions from accumulating indefinitely.

Locus 4.0 bundles Locus Memory 0.3.0. Memory behavior stays within the existing agent, workspace, and access boundaries. Your companion adds a name and appearance to a saved agent; character setup does not ingest files or create memories.

Inspect what was submitted

Use Memory on a chat turn or agent run to inspect the memory selected for that attempt. The inspector shows the final revalidated submission, current authorized content, matching and exclusion reasons, token limits, revision changes, and delivery state. It distinguishes selected, submitted, failed, and uncertain delivery.

Submitted to model means the context was delivered; it does not prove the model used it. Submission records retain encrypted references and reasons, not an unrestricted second copy of private content. Visibility still follows the current agent and workspace scope. Changing or forgetting memory cannot retract context already sent to a provider.

Memory owner and scope

The Memory owner picker changes which agent-scoped memories you are viewing and editing. Personal and workspace memory are shared independently of that selection.

Scope	Boundary
Personal	Available across workspaces for this local user.
Workspace	Bound to the canonical workspace.
Agent	Bound to the selected team member or primary agent.

Memory kinds are preference, fact, decision, procedure, and relationship. Each item can also carry tags, confidence, provenance, a source session/run, valid-from and valid-until dates, a pin, stale state, last-used time, use count, revision, and conflict/supersession links.

In an agent's advanced memory settings, Use Locus memory in native Codex turns is an explicit per-agent opt-in. Its scope, token budget, and allowed search/proposal tools remain bounded by that profile. Memory is supplied as reference data, not trusted system instructions. Helper results can offer Suggest workspace memory; the suggestion still needs human approval before recall.

Advanced Memory Settings

The screenshot shows a populated search index and an empty approved-memory set:

• 180 Files means 180 eligible project files are represented in the index.
• 455 Chunks means those files produced 455 searchable text segments.
• 0 Memories means no approved durable memory is currently visible for the active workspace and selected memory owner.
• FTS5 text search means the embedding model field is empty, so retrieval is lexical only.

The memory count is separate from the file and chunk counts. It also does not show how many candidates are waiting in the Inbox.

Workspace Search Index

The index is isolated by canonical workspace and stored locally in SQLite.

Control	Detailed behavior
Index this workspace	Enables project-file indexing for the current workspace.
Optional local Ollama embedding model	Leave empty for FTS5 lexical file search. Select a local model to add vector similarity to workspace indexing; approved-memory retrieval has its own settings below.
Additional exclusions	Comma-separated globs such as Generated/** or Fixtures/private-*.json.
Save	Stores enabled state, model, local Ollama host, and exclusion rules.
Rebuild Index	Reprocesses eligible files; use it after changing the embedding model or exclusions.
Delete All Workspace Knowledge	After confirmation, deletes the project index and workspace-scoped candidate and approved memory. It does not remove project files or chat transcripts.

Indexing follows Git ignore rules and uses content hashes for incremental updates. It refuses symlinks and paths that escape the canonical workspace, and skips hidden, vendor, build, binary, and oversized files.

The following never enter the index:

• Files matching Git ignore rules or your extra exclusion globs.
• Secret-shaped filenames and common key, certificate, and environment-secret names.
• Vendor/build folders and hidden paths.
• Binary files and files over 2 MB.
• Symlinks or path escapes.

If an embedding model is configured, text is sent only to the configured loopback Ollama /api/embed endpoint. If semantic embedding fails, FTS5 lexical search remains available.

Search results include relative paths, line ranges, freshness, and source type. They are evidence, not instructions: project text cannot change system instructions, permissions, or team membership.

Optional local semantic memory search

Under Memory retrieval, choose Optional local semantic memory search. Keyword retrieval is the default. Refresh the installed-model list, select an already installed Ollama embedding model, and explicitly save the setting. Locus validates the model's embedding support and identity; it does not download a model automatically.

Memory embeddings use a bounded loopback Ollama connection, and stored vectors are encrypted. If the selected model is unavailable or changes, keyword fallback remains available. Semantic retrieval is optional; the release does not claim a measured improvement in live-task quality.

How current recall works

Recall selects eligible approved items within the active personal, workspace, and agent grants, then ranks relevant evidence using lexical matching and optional local similarity. Pinning, confidence, and provenance do not override authorization or turn a preference into factual evidence.

Future-dated evidence is excluded. Current model-facing context excludes corrected or superseded historical evidence; historical browsing is explicit. Final submission revalidates scope, revision, validity, and deletion state so a previously selected item is not silently reused after it changes. Review the inspector's reasons instead of treating a search score as a confidence guarantee.

Conflicts and replacement

Locus surfaces same-topic alternatives instead of silently overwriting them.

• Keep Both approves the new item and preserves the older conflicting item.
• Replace Older approves the new item, records which IDs it supersedes, marks the older conflicts stale, and links each older item back to the replacement.

Feedback can be marked helpful, ignored, or incorrect. Incorrect feedback marks the memory stale for review; it should not be treated as current evidence.

Verified learning is reviewed work

Open Verified learning → Review learning for the current chat agent to inspect task episodes and propose reusable procedures. The evidence belongs to that agent and workspace. An assistant's claim of success or a user accepting an answer does not by itself establish a passing check.

Procedure eligibility requires independent verified task evidence, an explicit version-bound evaluation suite with negative cases, successful evaluation in disposable fixtures, and human approval. The displayed suite's fingerprint is carried into approval; editing it requires a fresh review. Invalidated or forgotten evidence can revoke eligibility.

Approving a procedure does not automatically install or execute instructions. This is separate from explicit Reusable Checks, and it does not collect corrections as automatic rules. Existing model, budget, permission, and cancellation controls still apply.

Backup and maintenance

Action	What it changes	What remains
Review Health	Marks expired approved memories stale and reports conflicts for review.	Index, files, chats, and non-expired memory.
Import Memory	Adds validated memories from a Locus Memory JSON export.	Existing index and source project.
Export Memory	Writes a deliberately readable JSON copy to your chosen file.	Encrypted local vault remains unchanged.
Delete All Workspace Knowledge	Deletes the workspace index and workspace-scoped candidate/approved memory.	Project files, chats, personal memory, and agent memory.
Delete All Memory	Deletes visible personal, workspace, and selected-agent candidate/approved memory.	Project index, project files, and chats.

warning

Memory export is readable text by design. Store the exported JSON like any other sensitive document. Deletion cannot be undone unless you exported memory first.

Encryption details

Memory content and optional semantic vectors are encrypted with AES-256-GCM. The backend's memory key is stored in its local memory/master.key file with user-only access; it is not protected by a separate per-application Keychain prompt. Continuity uses the backend memory encryption key.

Treat the local application profile and backups as private data. Memory export deliberately writes readable JSON. The separate Identity Vault uses its own edition-specific Keychain key.

Saved-chat search caches also use encrypted session envelopes, with full-text search indexes in memory. Raw transcript JSONL files are separate and remain unchanged; this is not encryption of every local file or forensic erasure of historical backups.

Restore protection

Memory status reports whether deletion checkpoints are protected, require recovery, or are unavailable. On macOS, the signed memory helper keeps a monotonic checkpoint in the login Keychain. It detects when a restored memory database has lost newer deletion history. An enrolled profile does not silently fall back to unprotected recall when its checkpoint is unavailable.

A checkpoint cannot reconstruct missing deletion entries. Prefer restoring the newer valid ledger. Offline recovery requires authenticated checkpoint evidence and explicit acknowledgment that previously forgotten records may be exposed; it is not a reset button. A locked Keychain must be unlocked, and unverifiable checkpoint state remains blocked. On hosts without supported checkpoint custody, the unavailable status is explicit.

See Credentials & Local Data and the offline recovery reference before recovering a backup.

Recommended defaults

• Start with keyword memory retrieval and FTS5 workspace search.
• Select an already installed local embedding model only when you want optional semantic retrieval.
• Exclude generated artifacts, private fixtures, and any project-specific sensitive paths.
• Approve durable decisions and conventions; reject transient task details.
• Run Review Health periodically if you use validity dates or keep many related decisions.