1use anyhow::{Result, anyhow, bail};
6use codewhale_memory::hooks::{self, Boundary, HookEvent, HookPolicy};
7use codewhale_memory::{
8 Access, ByteCounter, ContextBudget, Draft, Evidence, Freshness, Memory, MemoryBackend, Recall,
9 Scope, Snapshot, SourceKind, Status, Store, policy, workspace,
10};
11use std::{
12 fs,
13 path::{Path, PathBuf},
14 process::Command,
15};
16
17#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub enum MemoryScope {
19 Global,
20 Workspace,
21}
22#[derive(Debug, Clone, PartialEq, Eq)]
23pub struct MemoryHit {
24 pub id: i64,
25 pub text: String,
26 pub source: PathBuf,
27 pub line_start: usize,
28 pub line_end: usize,
29 pub stale: bool,
30}
31#[derive(Debug, Clone)]
32pub struct NativeMemoryStore {
33 root: PathBuf,
34}
35impl NativeMemoryStore {
36 pub fn new(root: impl Into<PathBuf>) -> Self {
37 Self { root: root.into() }
38 }
39 pub fn root(&self) -> &Path {
40 &self.root
41 }
42 pub fn global_path(&self) -> PathBuf {
43 self.root.join("global/MEMORY.md")
44 }
45 pub fn index_path(&self) -> PathBuf {
46 self.root.join("store.sqlite3")
47 }
48 pub fn from_global_path(path: &Path) -> Option<Self> {
49 if path.file_name()?.to_str()? != "MEMORY.md"
50 || path.parent()?.file_name()?.to_str()? != "global"
51 {
52 return None;
53 }
54 let root = path.parent()?.parent()?;
55 (root.file_name()?.to_str()? == "memory").then(|| Self::new(root))
56 }
57 pub fn from_memory_anchor(path: &Path) -> Self {
58 Self::from_global_path(path)
59 .unwrap_or_else(|| Self::new(path.parent().unwrap_or(Path::new(".")).join("memory")))
60 }
61 pub fn owner_scope() -> Scope {
62 Scope::user("local", "owner")
63 }
64 pub fn workspace_scope(id: &str) -> Result<Scope> {
65 safe_component(id)?;
66 Ok(Self::owner_scope().workspace(id))
67 }
68 pub fn workspace_id(workspace: &Path) -> Result<Option<String>> {
69 let out = Command::new("git")
70 .arg("-C")
71 .arg(workspace)
72 .args(["config", "--get", "remote.origin.url"])
73 .output()?;
74 if out.status.success() {
75 let value = String::from_utf8_lossy(&out.stdout).trim().to_owned();
76 if !value.is_empty() {
77 return Ok(Some(policy::sha256(value.as_bytes())));
78 }
79 }
80 let toplevel = Command::new("git")
81 .arg("-C")
82 .arg(workspace)
83 .args(["rev-parse", "--show-toplevel"])
84 .output()
85 .ok()
86 .filter(|out| out.status.success())
87 .map(|out| String::from_utf8_lossy(&out.stdout).trim().to_owned())
88 .filter(|path| !path.is_empty())
89 .map(PathBuf::from);
90 let anchor = toplevel
91 .or_else(|| workspace.canonicalize().ok())
92 .unwrap_or_else(|| workspace.to_path_buf());
93 Ok(Some(policy::sha256(anchor.as_os_str().as_encoded_bytes())))
94 }
95 pub fn open_structured(&self) -> Result<Store> {
96 Ok(Store::open(self.index_path())?)
97 }
98 fn scopes(&self, id: Option<&str>) -> Result<Vec<Scope>> {
99 let mut scopes = vec![Self::owner_scope()];
100 if let Some(id) = id {
101 scopes.push(Self::workspace_scope(id)?);
102 }
103 Ok(scopes)
104 }
105 fn hit(
106 &self,
107 store: &Store,
108 access: &Access,
109 m: &Memory,
110 snapshot: &Snapshot,
111 ) -> Result<MemoryHit> {
112 let source = match &m.draft.scope.workspace {
115 Some(id) => self.root.join("workspace").join(id).join("MEMORY.md"),
116 None => self.global_path(),
117 };
118 Ok(MemoryHit {
119 id: store.numeric_id(access, &m.id)?,
120 text: m.draft.body.clone(),
121 source,
122 line_start: 0,
123 line_end: 0,
124 stale: store.freshness(access, m, snapshot)? != Freshness::Current,
125 })
126 }
127 fn access_for(&self, id: Option<&str>) -> Result<Access> {
128 Ok(Access::operator(self.scopes(id)?)?)
129 }
130 pub fn remember(
131 &self,
132 scope: MemoryScope,
133 workspace_id: Option<&str>,
134 note: &str,
135 ) -> Result<MemoryHit> {
136 let selected = match scope {
137 MemoryScope::Global => Self::owner_scope(),
138 MemoryScope::Workspace => Self::workspace_scope(
139 workspace_id.ok_or_else(|| anyhow!("workspace scope requires an id"))?,
140 )?,
141 };
142 let access = Access::agent(vec![selected.clone()])?;
143 let mut store = self.open_structured()?;
144 let draft = Draft::note(
145 selected,
146 policy::excerpt(note, 80),
147 note,
148 Evidence {
149 kind: SourceKind::Agent,
150 uri: "codewhale:native-capture".into(),
151 locator: "Unreviewed capture through legacy native entry point".into(),
152 sha256: None,
153 observed_at: 0,
154 },
155 );
156 let key = format!("native-note:{}", policy::sha256(note.as_bytes()));
157 let r = store.capture(&access, &key, draft)?;
158 let mut hit = self.hit(&store, &access, &r.memory, &Snapshot::default())?;
159 hit.text = format!("Pending review in Context Lens: {}", hit.text);
160 Ok(hit)
161 }
162 pub fn remember_reviewed(
167 &self,
168 scope: MemoryScope,
169 workspace_id: Option<&str>,
170 note: &str,
171 ) -> Result<MemoryHit> {
172 let selected = match scope {
173 MemoryScope::Global => Self::owner_scope(),
174 MemoryScope::Workspace => Self::workspace_scope(
175 workspace_id.ok_or_else(|| anyhow!("workspace scope requires an id"))?,
176 )?,
177 };
178 let access = Access::operator(vec![selected.clone()])?;
179 let mut store = self.open_structured()?;
180 let draft = Draft::note(
181 selected,
182 policy::excerpt(note, 80),
183 note,
184 Evidence {
185 kind: SourceKind::User,
186 uri: "codewhale:operator".into(),
187 locator: "Explicit remember through an authenticated host surface".into(),
188 sha256: None,
189 observed_at: 0,
190 },
191 );
192 let key = format!("operator-note:{}", policy::sha256(note.as_bytes()));
193 let r = store.capture(&access, &key, draft)?;
194 let memory = if r.memory.status == Status::Candidate {
195 store.approve(
196 &access,
197 &r.memory.id,
198 r.memory.revision,
199 None,
200 &Snapshot::default(),
201 )?
202 } else {
203 r.memory
204 };
205 self.hit(&store, &access, &memory, &Snapshot::default())
206 }
207 pub fn revise(
208 &self,
209 scope: MemoryScope,
210 workspace_id: Option<&str>,
211 from: &str,
212 to: &str,
213 evidence: &str,
214 ) -> Result<MemoryHit> {
215 let selected = match scope {
216 MemoryScope::Global => Self::owner_scope(),
217 MemoryScope::Workspace => Self::workspace_scope(
218 workspace_id.ok_or_else(|| anyhow!("workspace id required"))?,
219 )?,
220 };
221 let access = Access::agent(vec![selected.clone()])?;
222 let mut store = self.open_structured()?;
223 let entries = store.list(&access, None, 500)?;
224 let matches: Vec<_> = entries
225 .iter()
226 .filter(|m| m.status == Status::Active && m.draft.body.trim() == from.trim())
227 .collect();
228 if matches.len() != 1 {
229 bail!(
230 "correction must match exactly one active note on the bounded page; use Context Lens UUIDs"
231 );
232 }
233 let old = matches[0];
234 let mut draft = Draft::note(
235 selected,
236 policy::excerpt(to, 80),
237 to,
238 Evidence {
239 kind: SourceKind::Agent,
240 uri: format!("codewhale:memory:{}", old.id),
241 locator: policy::excerpt(evidence, 256),
242 sha256: None,
243 observed_at: 0,
244 },
245 );
246 draft.kind = old.draft.kind;
247 draft.key = old.draft.key.clone();
248 let request = format!(
249 "native-correction:{}:{}",
250 old.id,
251 policy::sha256(format!("{to}\0{evidence}").as_bytes())
252 );
253 let r = store.capture(&access, &request, draft)?;
254 let mut hit = self.hit(&store, &access, &r.memory, &Snapshot::default())?;
255 hit.text = format!(
256 "Correction candidate; original unchanged. Review in Context Lens: {}",
257 hit.text
258 );
259 Ok(hit)
260 }
261 pub fn prompt_block(
264 &self,
265 workspace: &Path,
266 max_entries: usize,
267 max_chars: usize,
268 ) -> Result<Option<String>> {
269 let id = Self::workspace_id(workspace)?;
270 let access = self.access_for(id.as_deref())?;
271 let store = self.open_structured()?;
272 let snapshot = workspace::snapshot(workspace, store.dependency_paths(&access)?)?;
273 let (_report, packet) = store.context_packet(
274 &access,
275 &Recall {
276 limit: max_entries.clamp(1, 64),
277 snapshot,
278 ..Default::default()
279 },
280 &ByteCounter,
281 &ContextBudget {
282 max_units: max_chars,
283 max_bytes: max_chars,
284 max_entries,
285 },
286 )?;
287 Ok(if packet.selected.is_empty() {
288 None
289 } else {
290 Some(packet.text)
291 })
292 }
293 fn session_binding(
298 &self,
299 workspace: &Path,
300 session_id: &str,
301 ) -> Result<(Store, Access, Scope)> {
302 let id = Self::workspace_id(workspace)?;
303 let context_scope = match &id {
304 Some(id) => Self::workspace_scope(id)?,
305 None => Self::owner_scope(),
306 }
307 .session(session_id);
308 let mut scopes = vec![Self::owner_scope()];
309 if let Some(id) = &id {
310 scopes.push(Self::workspace_scope(id)?);
311 }
312 scopes.push(context_scope.clone());
313 let access = Access::operator(scopes)?;
314 Ok((self.open_structured()?, access, context_scope))
315 }
316 pub fn prompt_block_traced(
326 &self,
327 workspace: &Path,
328 session_id: &str,
329 max_entries: usize,
330 max_chars: usize,
331 ) -> Result<Option<String>> {
332 if session_id.is_empty()
333 || session_id.len() > 128
334 || !session_id
335 .bytes()
336 .all(|b| b.is_ascii_alphanumeric() || b"_-.:".contains(&b))
337 {
338 return self.prompt_block(workspace, max_entries, max_chars);
339 }
340 let (store, access, context_scope) = self.session_binding(workspace, session_id)?;
341 let snapshot = workspace::snapshot(workspace, store.dependency_paths(&access)?)?;
342 let query = Recall {
343 limit: max_entries.clamp(1, 64),
344 snapshot,
345 ..Default::default()
346 };
347 let key_material = serde_json::to_vec(
348 &serde_json::json!({"q":query.query,"snapshot":query.snapshot,"limit":query.limit,
349 "graph":query.expand_graph,"vector_cap":query.vector_scan_limit,"budget":[max_chars,max_entries],"unit":"utf8_bytes"}),
350 )?;
351 let request_key = format!("session-prompt:{}", policy::sha256(&key_material));
352 let budget = ContextBudget {
353 max_units: max_chars,
354 max_bytes: max_chars,
355 max_entries,
356 };
357 match store.prepare_context(
358 &access,
359 &context_scope,
360 session_id,
361 &request_key,
362 &query,
363 &ByteCounter,
364 &budget,
365 ) {
366 Ok(prepared) => Ok(if prepared.packet.selected.is_empty() {
367 None
368 } else {
369 Some(prepared.packet.text)
370 }),
371 Err(_) => self.prompt_block(workspace, max_entries, max_chars),
372 }
373 }
374 pub fn session_start(&self, workspace: &Path, session_id: &str) -> Result<usize> {
381 if session_id.is_empty()
382 || session_id.len() > 128
383 || !session_id
384 .bytes()
385 .all(|b| b.is_ascii_alphanumeric() || b"_-.:".contains(&b))
386 {
387 bail!("invalid session id for memory reconcile");
388 }
389 let (store, access, context_scope) = self.session_binding(workspace, session_id)?;
390 let snapshot = workspace::snapshot(workspace, store.dependency_paths(&access)?)?;
391 let event = HookEvent {
392 id: format!("session-start:{session_id}"),
393 boundary: Boundary::SessionStart,
394 trace_id: session_id.to_owned(),
395 sequence: 0,
396 observed_at: store.timestamp(),
397 explicit_user_request: false,
398 success: None,
399 };
400 let plan = hooks::plan(
401 &HookPolicy {
402 enabled: true,
403 auto_candidates: false,
404 recall_on_task: true,
405 },
406 &event,
407 );
408 let mut interrupted = 0usize;
409 for intent in &plan.intents {
410 if intent == &hooks::Intent::ReconcilePendingOperations {
411 interrupted = store
412 .context_receipts(&access, Some(session_id), &snapshot)?
413 .iter()
414 .filter(|r| r.stage != "dispatched")
415 .count();
416 }
417 }
418 store.record_completed_hook(&access, &context_scope, &event)?;
419 Ok(interrupted)
420 }
421 pub fn search(&self, query: &str, limit: usize) -> Result<Vec<MemoryHit>> {
422 self.search_scoped(None, None, query, limit)
423 }
424 pub fn search_for_workspace(
425 &self,
426 workspace: &Path,
427 query: &str,
428 limit: usize,
429 ) -> Result<Vec<MemoryHit>> {
430 let id = Self::workspace_id(workspace)?;
431 self.search_in_workspace(id.as_deref(), workspace, query, limit)
432 }
433 pub fn search_in_workspace(
436 &self,
437 workspace_id: Option<&str>,
438 workspace: &Path,
439 query: &str,
440 limit: usize,
441 ) -> Result<Vec<MemoryHit>> {
442 self.search_scoped(workspace_id, Some(workspace), query, limit)
443 }
444 fn search_scoped(
445 &self,
446 id: Option<&str>,
447 root: Option<&Path>,
448 query: &str,
449 limit: usize,
450 ) -> Result<Vec<MemoryHit>> {
451 let access = self.access_for(id)?;
452 let store = self.open_structured()?;
453 let snapshot = match root {
454 Some(root) => workspace::snapshot(root, store.dependency_paths(&access)?)?,
455 None => Snapshot::default(),
456 };
457 let report = store.recall(
458 &access,
459 &Recall {
460 query: query.into(),
461 limit,
462 snapshot: snapshot.clone(),
463 ..Default::default()
464 },
465 )?;
466 report
467 .hits
468 .iter()
469 .map(|h| self.hit(&store, &access, &h.memory, &snapshot))
470 .collect()
471 }
472 pub fn get_for_workspace(&self, workspace: &Path, id: i64) -> Result<Option<MemoryHit>> {
473 let workspace_id = Self::workspace_id(workspace)?;
474 self.get_scoped(workspace_id.as_deref(), Some(workspace), id)
475 }
476 fn get_scoped(
477 &self,
478 workspace_id: Option<&str>,
479 root: Option<&Path>,
480 id: i64,
481 ) -> Result<Option<MemoryHit>> {
482 let access = self.access_for(workspace_id)?;
483 let store = self.open_structured()?;
484 let m = match store.get_numeric(&access, id) {
485 Ok(m) => m,
486 Err(codewhale_memory::Error::NotFound) => return Ok(None),
487 Err(e) => return Err(e.into()),
488 };
489 if !matches!(m.status, Status::Active | Status::Stale) {
490 return Ok(None);
491 }
492 let snapshot = match root {
493 Some(root) => workspace::snapshot(root, store.dependency_paths(&access)?)?,
494 None => Snapshot::default(),
495 };
496 Ok(Some(self.hit(&store, &access, &m, &snapshot)?))
497 }
498 pub fn list_all(
499 &self,
500 scope: Option<MemoryScope>,
501 workspace_id: Option<&str>,
502 limit: usize,
503 ) -> Result<Vec<MemoryHit>> {
504 self.list_in_workspace(scope, workspace_id, None, limit)
505 }
506 pub fn list_in_workspace(
507 &self,
508 scope: Option<MemoryScope>,
509 workspace_id: Option<&str>,
510 workspace: Option<&Path>,
511 limit: usize,
512 ) -> Result<Vec<MemoryHit>> {
513 let scopes = match scope {
514 None => self.scopes(workspace_id)?,
515 Some(MemoryScope::Global) => vec![Self::owner_scope()],
516 Some(MemoryScope::Workspace) => vec![Self::workspace_scope(
517 workspace_id.ok_or_else(|| anyhow!("workspace id required"))?,
518 )?],
519 };
520 let access = Access::operator(scopes)?;
521 let Some(store) = Store::open_for_listing(&self.index_path())? else {
522 return Ok(Vec::new());
523 };
524 let snapshot = match workspace {
525 Some(root) => workspace::snapshot(root, store.dependency_paths(&access)?)?,
526 None => Snapshot::default(),
527 };
528 store
529 .list_current(&access, limit)?
530 .iter()
531 .map(|m| self.hit(&store, &access, m, &snapshot))
532 .collect()
533 }
534 pub fn import_legacy(&self, path: &Path) -> Result<bool> {
535 if !path.is_file() {
536 return Ok(false);
537 }
538 let meta = fs::symlink_metadata(path)?;
539 if meta.file_type().is_symlink() || meta.len() > 1024 * 1024 {
540 bail!("legacy import refused: symlink or size bound");
541 }
542 let text = fs::read_to_string(path)?;
543 let scope = Self::owner_scope();
544 let access = Access::operator(vec![scope.clone()])?;
545 let mut store = self.open_structured()?;
546 let report = codewhale_memory::import::markdown(
547 &mut store,
548 &access,
549 &scope,
550 "codewhale:legacy-memory",
551 &text,
552 )?;
553 if !report.rejected.is_empty() {
554 bail!(
555 "legacy import left {} rejected notes unchanged; inspect before retry",
556 report.rejected.len()
557 );
558 }
559 Ok(report.created > 0)
560 }
561 pub fn export(&self) -> Result<String> {
562 let store = self.open_structured()?;
563 let owner = Access::operator(vec![Self::owner_scope()])?;
564 let scopes = store.local_scope_inventory(&owner)?;
565 let mut output = String::from(
566 "# CodeWhale memory export\n\nNot an instruction file. This Markdown is not authoritative.\n",
567 );
568 for scope in scopes {
569 let access = Access::operator(vec![scope])?;
570 let mut after = None;
571 loop {
572 let batch = store.list(&access, after.as_deref(), 500)?;
573 if batch.is_empty() {
574 break;
575 }
576 for m in &batch {
577 output.push_str(&format!(
578 "\n## {} [{}] {}\n\n{}\n",
579 m.id,
580 m.status.as_str(),
581 m.draft.title,
582 m.draft.body
583 ));
584 }
585 after = batch.last().map(|m| m.id.clone());
586 }
587 }
588 Ok(output)
589 }
590 pub fn reindex(&self) -> Result<usize> {
591 let mut store = self.open_structured()?;
592 let access = Access::operator(vec![Self::owner_scope()])?;
593 store.reindex(&access)?;
594 let mut count = 0;
595 for scope in store.local_scope_inventory(&access)? {
596 let access = Access::operator(vec![scope])?;
597 let mut after = None;
598 loop {
599 let batch = store.list(&access, after.as_deref(), 500)?;
600 if batch.is_empty() {
601 break;
602 }
603 count += batch.len();
604 after = batch.last().map(|m| m.id.clone());
605 }
606 }
607 Ok(count)
608 }
609 pub fn delete_all(&self, scope: Option<MemoryScope>, workspace_id: Option<&str>) -> Result<()> {
610 let scopes = match scope {
611 Some(MemoryScope::Global) => vec![Self::owner_scope()],
612 Some(MemoryScope::Workspace) => vec![Self::workspace_scope(
613 workspace_id.ok_or_else(|| anyhow!("workspace id required"))?,
614 )?],
615 None => {
616 let store = self.open_structured()?;
617 let owner = Access::operator(vec![Self::owner_scope()])?;
618 let mut scopes = store.local_scope_inventory(&owner)?;
619 if scopes.len() >= 10000 {
620 bail!("Scope inventory reached its bound; delete narrower scopes explicitly");
621 }
622 if scopes.is_empty() {
623 scopes.push(Self::owner_scope());
624 }
625 scopes
626 }
627 };
628 let access = Access::operator(scopes)?;
629 let mut store = self.open_structured()?;
630 loop {
631 let batch = store.list(&access, None, 500)?;
632 if batch.is_empty() {
633 break;
634 }
635 for m in batch {
636 match store.get(&access, &m.id) {
637 Ok(current) => {
638 store.forget(&access, ¤t.id, current.revision)?;
639 }
640 Err(codewhale_memory::Error::NotFound) => {}
641 Err(e) => return Err(e.into()),
642 }
643 }
644 }
645 Ok(())
646 }
647}
648fn safe_component(value: &str) -> Result<()> {
649 if value.len() != 64
650 || !value
651 .bytes()
652 .all(|c| c.is_ascii_hexdigit() && !c.is_ascii_uppercase())
653 {
654 bail!("workspace identity must be a lowercase SHA-256 hash");
655 }
656 Ok(())
657}
658
659#[must_use]
667pub fn native_prompt_block(enabled: bool, memory_path: &Path, workspace: &Path) -> Option<String> {
668 if !enabled {
669 return None;
670 }
671 NativeMemoryStore::from_global_path(memory_path)?
672 .prompt_block(workspace, 32, 12_000)
673 .ok()
674 .flatten()
675}
676
677#[must_use]
683pub fn native_prompt_block_traced(
684 enabled: bool,
685 memory_path: &Path,
686 workspace: &Path,
687 session_id: &str,
688) -> Option<String> {
689 if !enabled {
690 return None;
691 }
692 NativeMemoryStore::from_global_path(memory_path)?
693 .prompt_block_traced(workspace, session_id, 32, 12_000)
694 .ok()
695 .flatten()
696}