# Company Kb > Use when company-kb — Company Knowledge Base Skill. Use when relevant to this domain. - Skill: `oyi77/company-kb` (Agent Skill) - Install (CLI): `npx skillmds add oyi77/company-kb` - Raw SKILL.md: https://api.skillmd.com/api/skills/oyi77/company-kb/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Research & Search - License: Apache-2.0 - Author: oyi77 (https://skillmd.com/u/oyi77) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/oyi77/company-kb --- # Company KB — Quick Reference **Role:** The Company Knowledge Base (company-kb) stores organization-specific memory — products, services, team members, clients, procedures, and operational history. While the parent `kb` skill manages the PARA structure and general knowledge retrieval, company-kb specializes in entity tracking, company-wide procedures, agent accountability records, and cross-referencing decisions to organizational context. Both agents and humans use this to maintain a single source of truth. ## Organization Structure Maintain a consistent directory layout so every agent and human can navigate without guessing: ``` ~/kb/company/ ├── products/ # Products and services (one dir per product) │ └── agent-platform/entity.yaml ├── clients/ # Client accounts, contacts, contracts ├── team/ # Team members, roles, skills ├── decisions/ # ADRs and policy decisions with rationale ├── operations/ # Session logs, runbooks, monitoring configs ├── vendors/ # Third-party tools, services, contracts ├── procedures/ # Step-by-step SOPs for recurring tasks ├── projects/ # Active and completed project records └── index.yaml # Cross-entity references and tag index ``` This layout is **not mandatory** — adapt to your org. What matters is predictability: every agent should be able to infer where a new entity lives without asking. ### Entity File Convention Each `entity.yaml` follows a minimal schema: ```yaml name: Agent Management Platform type: product status: active version: 2.1.0 team: Platform tags: [orchestration, mcp, agents] links: # Cross-references to other entities - type: client name: Acme Corp relation: deployed_at - type: decision name: pricing-tier-structure relation: informed_by created: 2026-01-10 updated: 2026-03-22 ``` Use the `links` field to build an entity graph. An agent reading about Acme Corp can immediately discover which products are deployed there and what pricing decisions affected them. ## Quick Start ### 1. Define Company Entities Register core entities — products, clients, team members, procedures: ```python import yaml from pathlib import Path KB_COMPANY = Path("~/kb/company").expanduser() def register_entity(entity_type, name, attributes): """Register or update a company entity.""" dir_path = KB_COMPANY / entity_type / name dir_path.mkdir(parents=True, exist_ok=True) file_path = dir_path / "entity.yaml" data = {"name": name, "type": entity_type, **attributes} file_path.write_text(yaml.dump(data, default_flow_style=False, sort_keys=False)) register_entity("products", "Agent Management Platform", { "status": "active", "version": "2.1.0", "team": "Platform", "description": "Multi-agent orchestration with MCP support", }) register_entity("clients", "Acme Corp", { "tier": "enterprise", "mrr": 49900, "onboarding_date": "2026-01-15", "account_manager": "Alice", "stack": ["notion", "slack", "custom-api"], }) ``` ### 2. Record Decisions and Procedures Capture why decisions were made and how procedures work: ```python def record_decision(title, context, decision, alternatives, date=None): from datetime import date as dt entry = {"title": title, "context": context, "decision": decision, "alternatives": alternatives, "date": str(date or dt.today())} Path(KB_COMPANY / "decisions" / f"{title.replace(' ', '-').lower()}.yaml").write_text(yaml.dump(entry)) record_decision("Pricing Tier Structure", "Needed to differentiate free vs pro features for launch", "Pro at $99/mo with unlimited agents, Standard at $49/mo with 5-agent limit", ["Single tier at $79/mo", "Usage-based pricing"]) ``` ### 3. Agent Accountability Log Track what each agent session accomplished: ```python import datetime, json def log_session(agent_id, task, outcome, facts_added=0): log = KB_COMPANY / "operations" / "session-log.json" logs = json.loads(log.read_text()) if log.exists() else [] logs.append({"agent": agent_id, "task": task, "outcome": outcome, "facts": facts_added, "ts": datetime.datetime.now().isoformat()}) log.write_text(json.dumps(logs, indent=2)) ``` ## One Focused Code Snippet — Quick Entity Lookup ```python def find_company_info(query, entity_type=None): """Search all company entities by name or attribute.""" results = [] search_dir = KB_COMPANY / (entity_type or "") for f in search_dir.rglob("*.yaml"): text = f.read_text().lower() if query.lower() in text: results.append(f.relative_to(KB_COMPANY)) return results[:10] ``` ## Multi-Agent Collaboration Patterns When multiple agents share the company KB, low-level races are rare (writes are additive), but **read-before-write** violations happen. Use a simple lock convention for destructive operations: ```python import fcntl, os LOCK_FILE = KB_COMPANY / ".entity.lock" def update_entity(entity_type, name, transform_fn): """Apply a transformation to an entity under file lock.""" file_path = KB_COMPANY / entity_type / name / "entity.yaml" with open(LOCK_FILE, "a") as lock: fcntl.flock(lock, fcntl.LOCK_EX) try: data = yaml.safe_load(file_path.read_text()) if file_path.exists() else {} new_data = transform_fn(data) file_path.write_text(yaml.dump(new_data, default_flow_style=False, sort_keys=False)) finally: fcntl.flock(lock, fcntl.LOCK_UN) def add_link(source_type, source_name, target_type, target_name, relation): """Atomically add a cross-entity link.""" def _add(data): links = data.get("links", []) links.append({"type": target_type, "name": target_name, "relation": relation}) data["links"] = links data["updated"] = str(datetime.date.today()) return data update_entity(source_type, source_name, _add) ``` **Naming convention for agent IDs** in session logs — use `/` so humans can trace which agent type performed what: ```bash # Example session log entries {"agent": "deploy-platform/20260322-a1b2", "task": "release v2.2.0", ...} {"agent": "support-oncall/20260322-c3d4", "task": "investigate client timeout", ...} ``` ## Cross-Project Memory Sharing via Entity Linking The `links` field in every entity.yaml creates a **navigable entity graph** across projects. An agent working on project Alpha can discover related entities in project Beta through shared references. Build automated link inference: ```python def auto_link_entities(entity_type, name): """Scan entity attributes and auto-create links to matching entities.""" file_path = KB_COMPANY / entity_type / name / "entity.yaml" if not file_path.exists(): return data = yaml.safe_load(file_path.read_text()) text = yaml.dump(data).lower() existing_links = {(l["type"], l["name"]) for l in data.get("links", [])} # Scan all entity dirs for name matches in attribute text for etype_dir in KB_COMPANY.iterdir(): if not etype_dir.is_dir() or etype_dir.name == entity_type: continue for ent_dir in etype_dir.iterdir(): ef = ent_dir / "entity.yaml" if not ef.exists(): continue ent_name = ent_dir.name if (etype_dir.name, ent_name) in existing_links: continue # Check if this entity's name appears in the source entity's text if ent_name.lower() in text: add_link(entity_type, name, etype_dir.name, ent_name, "references") ``` Run this after bulk imports or periodic index rebuilds. The resulting graph lets agents answer queries like "which clients are affected by the pricing change?" by traversing link chains. ### Graph Traversal Example ```python def traverse_links(start_type, start_name, max_depth=3): """BFS traversal of the entity link graph.""" visited = set() queue = [(start_type, start_name, 0)] while queue: etype, ename, depth = queue.pop(0) key = (etype, ename) if key in visited or depth > max_depth: continue visited.add(key) yield (etype, ename, depth) file_path = KB_COMPANY / etype / ename / "entity.yaml" if not file_path.exists(): continue data = yaml.safe_load(file_path.read_text()) for link in data.get("links", []): queue.append((link["type"], link["name"], depth + 1)) ``` ## Privacy Considerations and Access Boundaries Not every entity belongs in a shared KB. Define clear boundaries: | Data Class | Store in company-kb? | Example | |---|---|---| | Public/product info | Yes | Features, pricing, team roles | | Client metadata | Yes | Tier, stack, account manager | | Client PII | **No** — use encrypted vault | SSN, credit cards, personal addresses | | Credentials/secrets | **Never** — use Vault or env | API keys, passwords, tokens | | Internal procedures | Yes | Release checklists, escalation paths | | HR records | **No** | Salary, performance reviews | | Session logs (agents) | Yes, sanitized | Task + outcome, no raw data dumps | **Access boundary enforcement:** ```python PRIVACY_TYPES = {"team", "vendors"} def can_access(entity_type, viewer_role): """Check if a viewer role can access an entity type.""" if entity_type in PRIVACY_TYPES: return viewer_role in {"admin", "manager"} return True def register_entity_safe(entity_type, name, attributes, viewer_role="agent"): if not can_access(entity_type, viewer_role): raise PermissionError(f"{viewer_role} cannot write {entity_type} entities") return register_entity(entity_type, name, attributes) ``` When writing session logs, **strip sensitive fields** before persisting: ```python def sanitize_log(entry): """Remove sensitive keys from a log entry before writing.""" SENSITIVE_KEYS = {"api_key", "password", "token", "secret", "session_cookie"} if isinstance(entry, dict): return {k: sanitize_log(v) for k, v in entry.items() if k.lower() not in SENSITIVE_KEYS} if isinstance(entry, list): return [sanitize_log(item) for item in entry] return entry ``` ## Integration with 1ai-Hub Brain For agents operating in the 1ai-hub ecosystem, push critical entity changes to the brain for cross-session recall: ```python def remember_entity_change(entity_type, name, change_summary, importance=0.6): """Push entity changes to 1ai-hub brain for cross-session awareness.""" import subprocess, json payload = { "content": f"Company KB update: {entity_type}/{name} — {change_summary}", "category": "company-kb", "importance": importance } # Via hub brain_remember MCP tool subprocess.run([ "bash", "-c", f'echo '{json.dumps(payload)}' | xargs -I{{}} ' f'claude mcp brain_remember {{}}' ], capture_output=True) ``` **Search the brain for stale entity references before creating new ones:** ```bash # Search brain for existing entity context xd://mcp__ai_hub_brain_brain_search \ query="Acme Corp deployment status" \ service="gbrain" ``` This prevents duplicate entities and catches cross-project references that local YAML files would miss. ## Team Scenario — Real-World Workflow **Scenario:** Support agent "Alice" encounters a client timeout. She needs to know the client's tier, what products they use, and whether there's a known incident. ```python def triage_client(client_name, symptom): """Gather context for client support triage.""" # 1. Load client entity client_path = KB_COMPANY / "clients" / client_name / "entity.yaml" if not client_path.exists(): print(f"Unknown client: {client_name}") return client = yaml.safe_load(client_path.read_text()) print(f"Client: {client['name']} ({client.get('tier', 'unknown')})") # 2. Traverse links to find products and decisions for link in client.get("links", []): linked_path = KB_COMPANY / link["type"] / link["name"] / "entity.yaml" if linked_path.exists(): linked = yaml.safe_load(linked_path.read_text()) print(f" {link['relation']}: {link['name']} (v{linked.get('version', '?')})") # 3. Check operations log for recent incidents mentioning this client log_path = KB_COMPANY / "operations" / "session-log.json" if log_path.exists(): import json logs = json.loads(log_path.read_text()) recent = [e for e in logs[-50:] if client_name.lower() in e.get("task", "").lower()] for entry in recent: print(f" Recent: {entry['task']} → {entry['outcome']}") ``` Run this during intake — 3 seconds of structured lookup replaces 15 minutes of hunting through chat transcripts. ## Checklist - [ ] All product/service entities registered with name, status, version, and owning team - [ ] Client entities include tier, MRR, onboarding date, and primary contact - [ ] Decisions recorded with context, alternatives considered, and timestamp - [ ] Session log tracks agent activity for accountability and audit trails - [ ] Entity index cross-references related entities (e.g., a client linked to their active products) - [ ] File lock convention used for concurrent agent writes to the same entity - [ ] Sensitive data never written to YAML entities (use vault/encrypted store instead) - [ ] Privacy boundaries enforced for team/vendor/procedure entity types - [ ] Cross-project links maintained via `links` field; auto-linker run after batch imports - [ ] Critical entity changes pushed to 1ai-hub brain for cross-session recall ## Anti-Rationalization Table | Rationalization | Reality | |---|---| | "Entity tracking is just busywork" | When a client asks about a feature they discussed 3 months ago, a structured entity registry lets you answer in seconds instead of re-reading entire session transcripts. | | "Decisions are obvious, no need to write them down" | Three months later, the team has no idea why a $99/mo price was chosen over $79. Record context + alternatives or accept re-litigating every decision. | | "Only engineers need company KB" | Sales needs client history, support needs procedures, operations needs vendor records. A company-wide KB serves every function. Store it where agents AND humans can read it. | | "My agents all run in sequence, no lock needed" | Even sequential agents race on stale read-before-write. A file lock costs microseconds and prevents corrupted entity files that take hours to untangle. | | "I'll just keep this in my head / chat logs" | Human memory fades after 48 hours. Chat logs are unstructured and buried. A YAML entity is searchable, parseable, and survives session restarts. | | "Privacy is someone else's problem" | PII in a shared YAML file is a data breach waiting to happen. Classify every field before writing and never assume the consumer has authorized access. | ## When to Use Use this skill when working with company kb. ## Workflow See the parent skill for authoritative workflow documentation.