> ## Documentation Index > Fetch the complete documentation index at: https://powercontext.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Memory > Memory keeps conclusions you will reuse. It is not the full conversation. Write a Memory (Selected project knowledge that should matter later.) when the content will still influence later work. A decision already made, a constraint that still applies, the current project state, or a concrete next step all belong here. Do not pour the full conversation into Memory. A conversation may first become Source (Records what happened. Capture does not write durable knowledge.) evidence. Only the parts worth reusing across tasks belong in Memory. What you keep is the useful work. A shorter entry with a clear decision and scope usually recalls better than a transcript-shaped summary. It is also easier to revise or retire when the project changes. ## What belongs in Memory These are reasonable Memory entries. * “Regenerate the checked-in client after the public HTTP contract changes.” * “This project requires Python 3.11 or later.” * “OpenClaw project mode still isolates data by agent.” * “Run contract tests next and inspect generated-code drift.” They remain useful in another session or several days later. Temporary debug output, greetings, and one-off tool progress usually should not become Memory directly. Keep the Source first, then extract what matters. ## Memory is not an overwritable text row A Memory entry looks like one conclusion, but it has three identity layers. ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Memory Artifact Revision └── logical entry_id └── immutable entry_version_id ``` ### Artifact Revision An effective change to the Memory lifecycle creates another immutable Artifact Revision. The Revision stores the manifest and change set at that point. ### Logical entry `entry_id` identifies one piece of long-term knowledge. A revision of its content remains the same logical entry. ### Entry version `entry_version_id` identifies the exact content version. A revision creates a new entry version and retains its `previous_version_id`, evidence, and creating Memory Revision. An `entry_id` alone is not an exact citation. Maintenance operations also need the relevant Memory Revision and entry-version ID. ## The manifest defines current state The manifest in a Memory Revision is the authoritative directory for that Revision. Each item records a stable `entry_id`, an exact `entry_version_id`, the content hash, and an `active` or `inactive` state. `retire` changes an entry to inactive so default recall stops selecting it. The content and historical Revisions remain available. Revision is not in-place replacement either. It creates the next entry version, and the next Memory Revision points its manifest at that version. ## Two write paths Once identity and the manifest are clear, look at how content gets in. ### Explicit write When you know what should be retained, call `remember_memory` directly. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "scope_id": "project:powercontext-101", "kind": "decision", "text": "Regenerate and inspect the checked-in client before running contract tests." } ``` This path needs no model and no Source first. It may include `expected_revision` for concurrency control. If the content actually changes, it returns a Memory ref and an exact entry Citation. If the canonical form matches an existing entry, the write is no-op and may return the current Memory ref with `entry=null`. ### Extraction from Source The automatic path captures Source first, then lets the scheduler or `flush_memory` process a Source window. ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Source window → bounded evidence → model candidate → domain validation → canonicalization and deduplication → atomic Memory commit → cursor update ``` Model output is an untrusted candidate. It may cite only evidence IDs supplied to that operation, not an arbitrary Source or Artifact outside the request. PowerContext commits the Memory Revision, entry versions, and active search projections in one transaction. A failure cannot leave a committed Revision with a missing index update. Canonical duplicate content may become no-op instead of manufacturing a new Revision with no semantic change. > [!NOTE] > > Explicit writes and Source extraction can both produce Memory, but their lineage differs. To prove that an entry came from a particular Source, inspect its exact `source_refs` rather than relying on text similarity. ## Revise and retire An entry that already exists can still change, or it can be retired first. A revision targets the current exact Citation. New content creates another entry version, while the old version remains readable. Retirement also needs an exact target. ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Memory Revision + entry_id + entry_version_id ``` After retirement, default active listing and recall stop returning the entry. `include_inactive` supports audit. Old Artifact Revisions and entry versions still exist. If another worker advanced the Memory head, an older Citation conflicts. Read the current state and inspect the difference before deciding what to do. Do not guess the next Revision. ## How search works After a write, the next request has to find the entry again. Memory search does more than rank every text by one similarity score. It selects the current Memory head, then chooses a mode from the request and available capabilities. | mode | Requirement | Behavior | | - | - | - | | `fts` | FTS projection available | Recall from query-term evidence | | `vector` | Complete embedding model, profile, dimension, and backend vector capability | Vector retrieval only | | `hybrid` | FTS and vector available | Merge both result sets | | `auto` | Runtime selection | Prefer hybrid, otherwise use FTS | If query embedding is temporarily unavailable or times out, `auto` may fall back to FTS when FTS is available. An explicit `vector` or `hybrid` request must not silently change modes. The caller receives a capability error. ### Fusion and reranking Hybrid search combines FTS and vector ranks with reciprocal rank fusion. The current RRF constant is 60. Vector admission converts unit-normalized L2 distance to cosine similarity and applies a minimum similarity threshold. Results keep `matched_by`, showing whether FTS, vector, or both contributed. Optional reranking runs after retrieval. It may change final order, but it does not modify Memory or the search index. Once reranking begins, it uses the selected Revision snapshot instead of silently switching when another write advances the head. ## PreparedContext is not a copied search response A search hit does not mean this request will inject the whole entry. `prepare_context` retrieves coarse candidates, then a builder selects final content under one shared UTF-8 byte budget. The current builder uses several explicit limits. It takes up to 16 coarse Memory candidates and up to 8 Experience candidates. The final set has at most 8 items, and at most 2 of those may be Experience. Each item is capped at 2000 bytes. These are current implementation details and may change. The stable contract is that final content fits `max_bytes`, includes exact Citations, and is labeled `untrusted_history`. Two result states are normal. ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} empty → content is null, content_bytes is 0 ready → content is nonblank, content_bytes matches UTF-8 bytes ``` PreparedContext (A bounded view for one request. It includes Citations and is not a durable asset.) is input for this request. It does not become new Memory automatically. ## Walk through the OpenAPI example Write Memory explicitly. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "scope_id": "project:powercontext-101", "kind": "decision", "text": "Regenerate and inspect the checked-in client before running contract tests." } ``` Search it. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "scope_id": "project:powercontext-101", "query": "What should happen before contract tests?", "mode": "fts", "limit": 5 } ``` Inspect the response for these four facts. The hit `memory_ref` should identify the current exact Revision. The result should include `entry_id` and `entry_version_id`. `matched_by` should match the requested mode. The Citation from `prepare_context` should point to the same entry version. Then revise the content. ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Regenerate the checked-in client, inspect the diff, and then run contract tests. ``` The old Citation remains valid for historical reading, but it no longer identifies the current entry for revise or retire. ## Easy misdiagnoses ### `auto` returned FTS instead of hybrid Check the embedding model, profile ID, dimension, backend vector capability, and whether current Memory heads have complete vector projections. ### Flush processed Sources but created no Revision The model may have returned no-op, or canonicalization may have found duplicate content. Inspect Source lineage and the change set. ### Search returned a hit, but PreparedContext is empty PreparedContext also applies relevance, deduplication, and byte-budget constraints. A search hit is not guaranteed final selection. ### The Memory head changed during reranking The current search keeps the Revision snapshot selected at the start. A later search reads the new head. ## How you know the layers are separate 1. Artifact Revision, entry ID, and entry-version ID are three separate identities. 2. Retire means deactivate, not delete. 3. An explicit write needs no model and no Source first. 4. An extraction candidate must pass evidence and domain validation. 5. `auto` may fall back, but an explicit vector or hybrid request must not silently change modes. 6. PreparedContext is still temporary, untrusted, and bounded. When the objects are clear, write the first Memory in [Install and run the Server](https://powercontext.mintlify.site/en/basic-usage/install-and-run.md). To walk the capture path, use [Source and Memory in practice](https://powercontext.mintlify.site/en/basic-usage/source-and-memory.md). ## Next > [card] [See who continues the work](https://powercontext.mintlify.site/en/mental-model/handoff.md) > > Memory answers what the project should remember later. Handoff answers who continues and where they begin. > [card] [Write the first Memory](https://powercontext.mintlify.site/en/basic-usage/install-and-run.md) > > Start a local Server, write a Memory, find it, then get a cited PreparedContext. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.